# How to Report a Bug in TaxHacker: A Complete Guide for Contributors

> Easily report a bug in TaxHacker by following our GitHub Issue guide. Provide clear steps and environment details for quick resolution and contribution.

- Repository: [Vasily Zubarev/TaxHacker](https://github.com/vas3k/TaxHacker)
- Tags: how-to-guide
- Published: 2026-04-01

---

**To report a bug in TaxHacker, open a GitHub Issue using the "Bug report" template, provide a clear title, detailed reproduction steps, environment details, and reference specific source files like [`lib/uploads.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts) or [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts) to help maintainers triage efficiently.**

TaxHacker is a self‑hosted AI accountant built on Next.js, and its development workflow is centered entirely on GitHub. When you encounter crashes, parsing failures, or UI glitches, filing a detailed issue ensures the maintainers can reproduce the problem against the current CI/CD pipeline defined in [`.github/workflows/docker-release.yml`](https://github.com/vas3k/TaxHacker/blob/main/.github/workflows/docker-release.yml).

## Where to Report Bugs in TaxHacker

All bugs should be filed in the [vas3k/TaxHacker Issues](https://github.com/vas3k/TaxHacker/issues) tracker. Navigate to the repository, click **Issues**, then **New issue**. If the repository contains a "Bug report" template, select it—this pre‑populates fields for **Title**, **Description**, **Steps to reproduce**, **Expected behavior**, **Actual behavior**, and **Environment**.

Avoid submitting bugs via email or unrelated discussions; keeping everything in GitHub allows the maintainers to link commits, pull requests, and releases directly to your report.

## How to Structure a Bug Report for TaxHacker

A high‑quality report cuts triage time from days to minutes. Follow this structure when describing how to report a bug in TaxHacker.

### Start with a Clear Title and Summary

Summarize the problem in one line, mentioning the component and symptom. Good titles look like: *"AI extraction crashes in [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts) when processing Cyrillic PDFs"* or *"Upload handler in [`lib/uploads.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts) fails on files >5MB"*.

In the description, follow this exact pattern:

- **What you expected** – State the intended functionality (e.g., "PDF should parse and appear in the transactions table").
- **What actually happened** – Paste error messages, stack traces, or describe UI breakage.
- **Steps to reproduce** – List exact actions, sample files, and configuration values.
- **Screenshots or logs** – Attach images or terminal output.

### Document Environment and Dependencies

TaxHacker runs on Node.js and Next.js, often inside Docker. Provide the output of these commands:

```bash
node -v
npm list next
docker --version  # if self-hosted

```

Also disclose relevant **Environment Variables** (see the table in the [README](https://github.com/vas3k/TaxHacker/blob/main/README.md#environment-variables)) such as `OPENAI_API_KEY` or `DATABASE_URL`, redacting secrets.

Example environment block:

```markdown
- OS: macOS 14.2
- Node: 20.11.1
- Next.js: 15.2.4
- Docker: not used (local dev)

```

### Reference Specific Source Files

Deep linking to code helps maintainers jump straight to the logic. If you suspect the AI provider logic, mention [[`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts)](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts). For upload timeouts, cite [[`lib/uploads.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts)](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts) (line 41). Database schema issues belong in [[`models/transactions.ts`](https://github.com/vas3k/TaxHacker/blob/main/models/transactions.ts)](https://github.com/vas3k/TaxHacker/blob/main/models/transactions.ts).

## Example Bug Report Template

Copy this markdown snippet into your GitHub Issue and fill in the blanks:

```markdown
**Title**: AI extraction crashes on large PDF uploads

**Description**  
When uploading a PDF larger than 5 MB, the server returns a 500 error.

**Steps to reproduce**
1. Start the app (`npm run dev`).
2. Log in as an admin.
3. Go to **Upload → PDF** and select `large-invoice.pdf` (5.2 MB).
4. Click **Process**.

**Expected behavior**  
The document should be processed and displayed in the transactions table defined in `models/transactions.ts`.

**Actual behavior**  
Server response: `Error: PDF processing failed – internal server error`.

**Environment**
- OS: Ubuntu 22.04
- Node: 20.11.1
- Next.js: 15.2.4
- Docker: 24.0.7 (self-hosted)

**Relevant files**  
- `lib/uploads.ts` (line 41) – handles PDF upload size limits.
- `lib/previews/pdf.ts` (line 27) – generates preview images.

**Attachments**  
[Stack trace or screenshot here]

```

## Summary

- **Use GitHub Issues exclusively** – Navigate to `vas3k/TaxHacker/issues` and select the "Bug report" template.
- **Write actionable titles** – Mention the failing component (e.g., [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts)) and symptom.
- **Provide environment specs** – Include `node -v`, `npm list next`, and Docker versions.
- **Cite exact file paths** – Link to [`lib/uploads.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts), [`models/transactions.ts`](https://github.com/vas3k/TaxHacker/blob/main/models/transactions.ts), or workflow files like [`.github/workflows/docker-release.yml`](https://github.com/vas3k/TaxHacker/blob/main/.github/workflows/docker-release.yml).
- **Attach logs and screenshots** – Stack traces and images reduce back‑and‑forth.
- **Consider contributing a fix** – Fork the repo, branch from `main`, and reference the [Contributing section](https://github.com/vas3k/TaxHacker/blob/main/README.md#contributing) in the README.

## Frequently Asked Questions

### What information do I need to include when reporting a bug in TaxHacker?

You need a clear title, steps to reproduce, expected vs. actual behavior, your environment details (OS, Node version, Next.js version from [`package.json`](https://github.com/vas3k/TaxHacker/blob/main/package.json)), and any relevant source files like [`lib/uploads.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts) or [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts). Screenshots and stack traces accelerate debugging.

### Where does TaxHacker handle PDF upload errors?

PDF upload logic resides in [[`lib/uploads.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts)](https://github.com/vas3k/TaxHacker/blob/main/lib/uploads.ts). Line 41 typically contains the size validation or stream handling that triggers when files exceed limits. Preview generation happens in [`lib/previews/pdf.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/previews/pdf.ts) around line 27.

### How does the TaxHacker CI pipeline handle bug fixes?

TaxHacker uses the workflow defined in [[`.github/workflows/docker-release.yml`](https://github.com/vas3k/TaxHacker/blob/main/.github/workflows/docker-release.yml)](https://github.com/vas3k/TaxHacker/blob/main/.github/workflows/docker-release.yml) to build Docker images on every push. When you submit a pull request that closes an issue, the CI system runs regression tests to ensure the fix does not break existing functionality before merging to `main`.

### Can I submit a fix directly instead of just reporting?

Yes. If you know how to resolve the bug, fork the repository, create a feature branch, implement the change in the relevant file (e.g., [`lib/llm-providers.ts`](https://github.com/vas3k/TaxHacker/blob/main/lib/llm-providers.ts)), and open a Pull Request that references the issue number. Follow the workflow outlined in the repository's Contributing section.