Troubleshoot — KYC / KYB

Service will not start

• Poetry install on Python ≥ 3.10?
• GOOGLE_APPLICATION_CREDENTIALS readable?
• TensorFlow / insightface install failures → use service Docker image.

Prembly / vendor errors

• Distinguish FastAPI 422 (payload) from upstream 5xx / vendor downtime.
• Confirm PREMBLY_API_KEYS / PREMBLY_APP_ID for that environment.

Face / liveliness failures

• Match image field names and encoding to Swagger.
• Verify weights/paths under src/models/face_verify/ and anti-spoof modules.

Screening empty or timeouts

• OpenSanctions / Serper / network / quotas.
• BigQuery permission errors after a successful screen → audit persistence path.

goAML XML not available via API

Expected today: library under src/report/aml_goaml/ without an app.py route. Run offline pipeline or track a future HTTP/job entrypoint.

Static OpenAPI on docs site is stale

Regenerate docs/openapi/kyc-kyb.openapi.json and rebuild MkDocs. Live /openapi.json on a running revision wins until refresh.