Troubleshooting¶

Start with the visible symptom, then verify configuration and the boundary where the request fails. Do not print entire environment files or authorization headers while diagnosing.

Flutter web port is already in use¶

If Flutter reports Only one usage of each socket address ... is normally permitted, another process owns the requested port.

PowerShell¶

Get-NetTCPConnection -LocalPort 8000 |
  Select-Object LocalAddress, LocalPort, State, OwningProcess

Bash¶

netstat -ano | grep ':8000'

Stop the known development process or choose another port:

flutter run -d chrome --web-port 8001

Browser cannot reach the API¶

Confirm:

the backend is listening on the expected port;
Flutter was started with an API URL that includes /api/v1;
the browser origin is in CORS_ORIGINS;
HTTPS pages are not calling an HTTP API;
a reverse proxy is forwarding the full path.

Test the public health endpoint before debugging authentication.

eGovPH or eVerify returns 401¶

A 401 usually means the token presented to that endpoint is absent, expired, for the wrong environment, or the wrong kind of token. Partner code and partner secret are credentials used server-side to obtain/exchange a token; they are not substitutes for a Bearer access token.

Confirm sandbox URLs and sandbox credentials are paired.
Start a fresh flow; exchange codes are typically short-lived and single-use.
Keep the device clock accurate.
Do not scan an eVerify identity QR into an eGovPH SSO exchange-code flow; they are separate contracts.
Check redacted server logs for the provider status and correlation ID.

Do not paste the token into an issue, chat, or documentation page.

QR scanner is black¶

On Flutter web, camera access requires a secure context (https:// or local development), browser permission, a selected video input, and an available camera.

Confirm the browser did not block camera permission.
Close other applications using the camera.
Test on a real phone if the desktop has no camera.
Verify the SDK/Flutter camera element has non-zero dimensions.
Show a permission-denied or no-camera message instead of an indefinite black view.

AI response is unrelated¶

Check the normalized request and catalog candidate scores before blaming the model. Ambiguous conversation should remain conversational; journey creation requires a service-oriented interpretation with sufficient confidence.

Confirm the workflow catalog is seeded.
Confirm the provider response passed schema validation.
Inspect redacted routing reasons and thresholds.
Retry with the AI provider disabled to compare deterministic routing.
Add a regression test for the exact fabricated phrase.

Never send real identity or document content to a debugging prompt.

Journey does not persist¶

Verify that the creation endpoint returned a journey ID, the client stored/refetched it, and subsequent milestone calls use the same authenticated user. Check database writes and transaction rollback messages. A UI-only progress animation must follow—not replace—the persisted backend transition.

Documentation build fails¶

Run:

python -m mkdocs build --strict

The error normally identifies a missing navigation file, invalid Markdown reference, or template issue. Do not commit the generated site/ directory.