Troubleshooting & Fallbacks

Relevant source files

The following files were used as context for generating this wiki page:

• backend.py
• forms.py
• taxcalc.py
• utils/auto_mapper.py
• SETUP.md
• README.md
• parsing/validator.py

The Rosy Tax Processor is designed with a "graceful degradation" philosophy, ensuring that the system remains functional even when preferred dependencies or templates are missing. This architectural approach focuses on providing alternative processing paths for document ingestion, field mapping, and tax form generation.

The scope of this system includes automated recovery from missing OCR engines, semantic model failures, and PDF template absences. It ensures that the core objective—extracting tax data and providing a reviewable draft—is met regardless of the environment's limitations.

## Dependency & Environment Fallbacks

The system identifies missing software dependencies at runtime and switches to simpler, built-in logic to avoid application crashes.

### OCR and Ingestion Fallbacks

If the Tesseract OCR engine is not installed on the host system, the application provides a specific error message and recommends using digital PDF files instead of images. Digital PDFs are processed using native libraries like PyMuPDF or pdfminer.six which do not require external binaries.

Sources: SETUP.md:33-36, README.md:144-147

### Semantic Mapping Fallbacks

The auto_mapper.py utility attempts to use sentence-transformers for high-accuracy semantic field matching. If this library or its models are unavailable, the system falls back to a normalized string similarity algorithm.

The fallback similarity logic uses difflib.SequenceMatcher and a token-based bonus system to match parsed fields (e.g., "wages") to PDF template fields (e.g., "FormWages").

Sources: utils/auto_mapper.py:44-67, README.md:43-43

## Form Generation & Template Fallbacks

The PDF generation engine in forms.py utilizes a tiered fallback strategy to ensure a document is produced even if templates or filling libraries fail.

### PDF Generation Tiers

1. Fillable PDF Template: The system first attempts to use pdfrw to fill 1040_fillable.pdf using an exact field map or the auto-mapper.
2. ReportLab Canvas: If pdfrw is missing or the template is not found, it attempts to generate a new PDF from scratch using reportlab.
3. Plain Text Draft: If reportlab is also unavailable, the system generates a standard .txt file containing the extracted fields and tax estimates.

Failure Scenario	Fallback Action	Resulting File
Missing 1040_fillable.pdf	Invoke generate_1040_pdf	draft_1040.pdf (Non-fillable)
pdfrw not installed	Catch exception, use ReportLab	draft_1040.pdf (Non-fillable)
reportlab not installed	Invoke _generate_text_draft	draft_1040.txt

Sources: forms.py:68-105, forms.py:126-140, README.md:44-44

## Data Validation & Calculation Fallbacks

The system handles missing or malformed data through validation warnings and default configuration values.

### Tax Bracket Fallbacks

The tax calculator attempts to load current year brackets from tax_brackets.json. If this file is missing or corrupted, the system falls back to a hardcoded minimal set of progressive tax brackets for "single" and "married" statuses.

Sources: taxcalc.py:21-42

### Field Validation Issues

Rather than failing the entire pipeline, the validator.py module identifies "issues" (e.g., missing Box 1 wages, negative values, or unusually large amounts) and returns them as a list to the UI. This allows the user to correct data in the frontend before finalization.

Sources: parsing/validator.py:17-54, backend.py:84-88

## Common Troubleshooting Steps

Based on the project's documentation and setup guides, common issues can be resolved via the following configurations:

Problem	Resolution	Source
Port 5000 in use	Run via python -c "from backend import app; app.run(port=5001)"	SETUP.md:39-43
Tesseract error	Use PDF files or install Tesseract binary	SETUP.md:33-36
Model download slow	Ensure internet access on first run (approx. 500MB)	SETUP.md:58-61
Missing fields in PDF	Use tools/inspect_pdf_fields.py to verify template keys	templates/README.md:1-12

Sources: SETUP.md:32-48, templates/README.md:7-12

The Rosy Tax Processor's robust fallback architecture ensures that environment-specific limitations do not prevent the generation of tax results. By layering dependencies—from complex ML models down to basic string matching, and from fillable PDFs down to plain text—the system maintains high availability for its core processing tasks.