Skip to main content

Troubleshooting

API crash loop / will not start​

  • Postgres unreachable: check FALCONTALON_DB_URL from the API process.
  • Encryption key not valid base64 / wrong length.
  • FALCONTALON_PYTHON_BIN missing only matters when a custom transformer runs.

401 unauthorized​

  • Console: VITE_OIDC_AUTHORITY/VITE_OIDC_CLIENT_ID missing on the console, or API FALCONTALON_OIDC_ISSUER_URL unset (OIDC path dead). If VITE_OIDC_AUTH_ENABLED=false, use the sidebar API key instead.
  • Workers / tooling: X-API-Key must match FALCONTALON_KEY_API. Query-string keys are rejected.
  • GET /api/health is public; do not use it as an auth test.

Workers page empty​

Workers are not registering. Check that FALCONTALON_API_URL is reachable from the worker, that FALCONTALON_KEY_API matches the API, and worker logs for register/claim errors. The reaper deletes instances after 90s without a heartbeat.

Also confirm the API is FALCONTALON_WORKER_MODE=cluster.

Executions stuck in claimed / running​

  • Worker died. Wait for lease TTL (60s) or reaper (90s). The row should return to scheduled unless retries are exhausted.
  • Heartbeats not reaching the API.
warning

Partial sink writes from abandoned runs are not rolled back. Re-runs may duplicate sink output.

Kafka has no messages​

  • Datasource brokers, topic, or SASL/TLS do not match the Kafka you deployed.
  • Consumer group already at the end of the topic; execution idled out after 5s with nothing new.
  • Wrong topic name on source vs sink.

Pipeline run fails immediately​

  • SFTP source or local sink selected in the UI — not implemented at runtime.
  • HTTP/S3 URL is private and FALCONTALON_ALLOW_PRIVATE_URLS is false.
  • First step is not a classifier, or two classifiers are adjacent.
  • Custom transformer missing.

Console cannot reach API​

  • VITE_API_BASE_URL does not match the API URL the browser should call.
  • Console origin not in FALCONTALON_CORS_ORIGINS.

Migrations​

Apply dbmate against the same database as FALCONTALON_DB_URL before the API serves traffic.