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

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 or 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.

Where to Report Bugs in TaxHacker

All bugs should be filed in the 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 when processing Cyrillic PDFs" or "Upload handler in 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:

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

Also disclose relevant Environment Variables (see the table in the README) such as OPENAI_API_KEY or DATABASE_URL, redacting secrets.

Example environment block:

- 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). For upload timeouts, cite [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).

Example Bug Report Template

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

**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) and symptom.
• Provide environment specs – Include node -v, npm list next, and Docker versions.
• Cite exact file paths – Link to lib/uploads.ts, models/transactions.ts, or workflow files like .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 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), and any relevant source files like lib/uploads.ts or 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). Line 41 typically contains the size validation or stream handling that triggers when files exceed limits. Preview generation happens in 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) 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), and open a Pull Request that references the issue number. Follow the workflow outlined in the repository's Contributing section.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}