Troubleshooting

Activation

"Activation code is not in <payload>.<signature> form" — the paste caught only part of the code. Copy it again from Settings → Self-hosted licence in your cloud account; do not retype it.

"This activation code is for '…', not Busabase Premium" — a code for a different product. There is nothing to fix on this instance.

The instance has gone read-only — the licence expired. Everything is intact and readable; paste a renewal code on the licence page and writes resume immediately. That page stays reachable while expired specifically so this is possible. See Licensing.

"Seats are full (50/50)" when inviting — you are at the seat limit. Existing members are unaffected. Remove a member to free a seat, or talk to us about raising the limit.

Start-up

The container starts and then stops — usually the database. Check the logs first:

docker compose logs app        # Compose
docker logs busabase           # all-in-one

A database that cannot be reached produces one clear line saying so, and the healthcheck reports unhealthy rather than the container pretending to be up.

Migrations failed — the app deliberately does not start; it stays in Created and its port never answers. docker compose logs migrate shows the failing SQL statement and the database error, though not the file it came from — grep the migrations directory for that statement to find it. Do not start the app manually to "get it running": it would be running against a schema it does not match.

Signing in returns 403 Invalid origin — APP_URL (or BETTER_AUTH_BASE_URL) does not match the browser's address bar. The sign-in endpoint validates the request's Origin header, so scheme, hostname and port all have to agree; the UI shows Invalid origin directly rather than bouncing silently.

Attachments

Everything works but every upload fails — the S3 credentials in .env and seaweed-s3.json do not match. This is what init.sh exists to prevent; if the files were edited by hand, one of them was missed.

Uploads fail at a certain size — the reverse proxy. client_max_body_size has to be at least as large as your largest attachment; the proxy rejects the request before Busabase sees it.

"Not enough storage space" — the disk is full. Everything else keeps working; only writes to object storage fail. Free space or raise SEAWEEDFS_VOLUME_LIMIT_MB.

Downloads fail with 403 against a non-AWS S3 store — some S3-compatible servers reject the checksum headers the AWS SDK adds by default. Busabase sets requestChecksumCalculation and responseChecksumValidation to WHEN_REQUIRED for exactly this reason; if you are on a proxy that adds them back, that is where to look.

Agents and streaming

Agent responses arrive all at once at the end instead of streaming — proxy_buffering off is missing from the reverse proxy config. Nothing is broken; the output is being held by the proxy until the turn completes.

Network

The instance is on an isolated network — that is fine and fully supported. Licence verification is local: nothing is sent anywhere, so an air-gapped host activates exactly like a connected one.

Collecting a support bundle

Send this with any report. It contains logs, health output and image metadata, and no credentials — the generated secrets live in /data/.credentials and are never logged.

All-in-one:

docker logs --tail 500 busabase > sb-logs.txt 2>&1
curl -s http://localhost:3000/api/health > sb-health.json
docker inspect busabase --format '{{.Config.Image}} {{.State.Status}}' > sb-meta.txt
tar czf busabase-support.tar.gz sb-logs.txt sb-health.json sb-meta.txt

Compose:

./support-bundle.sh

The Compose script also includes the names of your environment variables with every value replaced by <redacted>, which is often enough to spot a missing or misspelled setting without you sending us a single secret.

Send it to support@busabase.com.