Sankofa Docs
Open app
DocsSelf-hostingTroubleshooting
Self-hosting

Troubleshooting

Common local setup issues around API keys, ClickHouse connectivity, CORS, and replay-related storage configuration.

Source of truthserver/infra/docker-compose.ymlserver/engine/.env.exampleserver/engine/ee/replay/plugin.go

Missing or invalid API key

Symptoms:

  • 401 on ingest because x-api-key is missing
  • 403 on ingest because the key does not resolve to a project

Check:

  • that the project exists
  • that you are sending the correct live or test key
  • that your requests target the correct environment

ClickHouse connection problems

Check:

  • CLICKHOUSE_ADDR
  • CLICKHOUSE_USER
  • CLICKHOUSE_PASSWORD
  • CLICKHOUSE_DB

If you are using the compose file, make sure the Sankofa service can resolve the clickhouse hostname and that the health check has passed.

Browser access and CORS

If browser requests fail, review CORS_ALLOWED_ORIGINS and make sure the docs, website, or dashboard origin is included.

Replay storage failures

Replay uploads depend on the enterprise replay plugin and the B2-compatible storage settings in the replay plugin:

  • B2_ENDPOINT
  • B2_KEY_ID
  • B2_APP_KEY
  • B2_BUCKET_NAME

Previous

Production architecture

Understand the role of the engine, SQLite, ClickHouse, and enterprise plugins in a self-hosted deployment.

Next

Enterprise features

Overview of the enterprise-only routes and plugin-backed capabilities present in this repository.