how to contribute debugging

Debugging

Use this page for common failure modes while developing CSV Align. For validation commands, see testing. For release packaging context, see deployment.

Built frontend assets are missing

Symptom:

cargo run exits with a message that built frontend assets could not be found.
Tauri build with CSV_ALIGN_USE_PREBUILT_FRONTEND=1 exits because /Users/vriesd/projects/csv-align/frontend/dist/index.html is missing.

Checks:

(cd /Users/vriesd/projects/csv-align/frontend && npm run build)
cargo run --manifest-path /Users/vriesd/projects/csv-align/Cargo.toml

The local web lookup lives in /Users/vriesd/projects/csv-align/src/api/app.rs. The Tauri build hook lives in /Users/vriesd/projects/csv-align/scripts/build_frontend_for_tauri.sh.

Session not found

Symptom:

Browser API returns { "code": "not_found", "error": "Session not found" }.
Tauri command serialization returns the same error shape.
Frontend cleanup ignores missing-session deletes but surfaces missing sessions for active operations.

Checks:

Confirm the frontend created a session through /Users/vriesd/projects/csv-align/frontend/src/services/tauri.ts.
Confirm the request path includes the current session_id.
Inspect session lifecycle behavior in /Users/vriesd/projects/csv-align/src/backend/store.rs and /Users/vriesd/projects/csv-align/src/backend/session.rs.
Reproduce through /Users/vriesd/projects/csv-align/tests/response_contracts.rs or /Users/vriesd/projects/csv-align/tests/session_store_integration.rs.

CSV parse errors

Symptom:

Upload fails with duplicate header, empty file, oversized file, malformed row, or parse error messages.
A row reports a different column count than the header row.

Checks:

/Users/vriesd/projects/csv-align/src/data/csv_loader.rs uses header-aware CSV parsing, delimiter detection for comma or semicolon, BOM trimming, and duplicate header rejection.
/Users/vriesd/projects/csv-align/src/backend/workflow.rs rejects empty files and files over 25 MiB.
Browser upload body limits are configured in /Users/vriesd/projects/csv-align/src/api/app.rs.
Regression coverage lives in /Users/vriesd/projects/csv-align/tests/csv_loader_integration.rs and /Users/vriesd/projects/csv-align/tests/local_file_loading_integration.rs.

Flexible key limits

Symptom:

Compare fails with a message about too many flexible key candidates or comparisons.

Cause:

Flexible ** key matching can produce broad candidate sets. Guardrails in /Users/vriesd/projects/csv-align/src/backend/workflow.rs call limit helpers in /Users/vriesd/projects/csv-align/src/comparison/engine.rs before running the full comparison.
Current limits are 10,000 flexible key candidates and 1,000,000 flexible key comparisons.

Checks:

Narrow selected key columns.
Add literal anchors around ** patterns.
Disable flexible key matching if exact matching is sufficient.
Use /Users/vriesd/projects/csv-align/tests/comparison_engine_integration.rs for regression examples.

Tauri file dialogs do not open

Symptom:

Desktop save or load actions for pair-order files, snapshots, CSV export, or HTML export return without showing the expected native dialog.

Checks:

Verify dialog permissions in /Users/vriesd/projects/csv-align/src-tauri/capabilities/default.json.
Verify the command uses tauri_plugin_dialog helpers in /Users/vriesd/projects/csv-align/src-tauri/src/commands.rs.
Verify the frontend invokes the correct command name from /Users/vriesd/projects/csv-align/frontend/src/services/tauriCommands.ts.
Run /Users/vriesd/projects/csv-align/src-tauri/src/pair_order_tests.rs and /Users/vriesd/projects/csv-align/src-tauri/src/comparison_snapshot_tests.rs.

Release packaging failures

Symptom:

CI or tagged release fails while validating Linux metadata, signing Debian packages, building the APT repository, or publishing macOS DMGs.

Checks:

For version mismatches, run python3 /Users/vriesd/projects/csv-align/scripts/check_release_metadata.py --expected-tag vX.Y.Z.
For Debian desktop id drift, check /Users/vriesd/projects/csv-align/scripts/normalize_linux_deb_desktop_id.py.
For package metadata failures, check /Users/vriesd/projects/csv-align/scripts/validate_linux_deb_metadata.py.
For RPM failures, check /Users/vriesd/projects/csv-align/scripts/build_rpm_package.py.
For APT repository failures, check /Users/vriesd/projects/csv-align/scripts/build_apt_repository.py and /Users/vriesd/projects/csv-align/scripts/install-apt-repo.sh.
For macOS failures, verify the Apple signing and App Store Connect API key secrets listed in /Users/vriesd/projects/csv-align/docs/releasing.md.

Key source files

File	Debug area
`/Users/vriesd/projects/csv-align/src/api/app.rs`	Frontend dist lookup, API routes, and HTTP body limits.
`/Users/vriesd/projects/csv-align/scripts/build_frontend_for_tauri.sh`	Tauri prebuilt frontend contract.
`/Users/vriesd/projects/csv-align/src/backend/error.rs`	Shared HTTP and Tauri error serialization.
`/Users/vriesd/projects/csv-align/src/backend/store.rs`	Session count, idle, and memory eviction.
`/Users/vriesd/projects/csv-align/src/data/csv_loader.rs`	CSV decoding, delimiter detection, header validation, and malformed row errors.
`/Users/vriesd/projects/csv-align/src/comparison/engine.rs`	Flexible key limits and comparison result generation.
`/Users/vriesd/projects/csv-align/src-tauri/capabilities/default.json`	Desktop permissions for dialogs and webview windows.
`/Users/vriesd/projects/csv-align/.github/workflows/ci.yml`	CI validation and Linux package artifact production.
`/Users/vriesd/projects/csv-align/.github/workflows/release.yml`	Tagged release validation, signing, package upload, APT Pages deploy, and DMG publishing.