Troubleshooting

Start with the visible control or error. Avoid compensating for a missing or incorrect input by changing an unrelated forecast output.

Setup or schema fails

Run pnpm run doctor from the application root. Resolve the reported dependency, configuration, storage or database issue. It names missing variables without requiring you to share their values.

A review-storage migration message means the database is behind the application. Apply the checked-in migrations with pnpm db:migrate, then retry. Do not recreate the database as a first response.

The number exists but remains provisional

Inspect starting-cash reconciliation, account/date coverage and forecast exceptions. A met goal and a verified result are different things. Accepting an exception at sign-off does not fix its underlying source control.

See Starting cash and coverage.

An expected receipt seems to be counted twice

Check whether the actual is posted, allocated to the correct expectation, and within the UTC cutoff. Then check for a duplicate import or an independent driver representing the same obligation.

An amount match is not identity. Use Forecast settlement for fulfillment and Import corrections for duplicate or changed source rows.

A late payment vanished from dated cash

Look in overdue or unplaced expectations. These are deliberately excluded from dated weekly totals until reviewed. Reschedule with evidence for the new date rather than assuming the amount is available now.

A recurring forecast stops capturing

Inspect the policy’s active window and stale reason. Changed supporting journals, document approvals or driver terms may require renewal or a reviewed replacement. Captured obligations remain in history.

Use Recurring recovery; do not approve an old hash after its sources changed.

Recognition cannot continue

Link the actual payment and recognition journals for the completed schedule. Check exact cumulative account debits and credits, posting basis, date scope, currency and reversals. An ambiguous working-capital account or unsupported treatment remains an exception.

See Recognition continuity.

Approval says the preview changed

Refresh, inspect the new effects and approve the new preview. A token protects the reviewed input state; it is not an authorization that remains valid after changes. If another person changed a record, reload its current version before resubmitting your intended action.

A review cannot be signed

Check that it is submitted, the signer is the assigned reviewer, the snapshot is current, and no exception task is open. A resolved task whose issue persists still blocks signing. Refresh after fixing records, or accept the exception explicitly with a reason. Self-review requires acknowledgement.

Accuracy has no score

Confirm that the baseline contains captured expectations preserved before the expected event and payments, and that actual allocations complete the obligations. Pending, excluded and absent observations must not be converted into zero-error observations.

Imports cannot be approved

Inspect document identity, statement scope, row mappings, reviewed proposals and closed-period controls. Use partial update for overlapping exports with absent rows that should remain. Unsupported FX and missing provenance need separate support.

Get useful help

Record the application revision, affected workflow, bounded error text, expected behavior and a synthetic reproduction. Include whether typecheck, accounting acceptance or isolation checks fail. Do not post real statements, full financial snapshots, secrets, private source text or production connection strings.

Use Contributing for development checks and the repository’s private security-reporting path for vulnerabilities.