Common Errors

Frequently encountered errors and step-by-step diagnosis.

Database Connection ErrorsCopy Anchor Link

Symptom: "Database connection failed" on StartupCopy Anchor Link

1. Is Postgres actually up?

   Copy Text

   pg_isready -d "$DATABASE_URL"

   If this fails, start Postgres (Docker users: docker compose up -d postgres) before continuing.

2. Does DATABASE_URL in .env hold the credentials Postgres expects?

   Copy Text

   psql "$DATABASE_URL"

   If this fails with password authentication failed, the password in the URL is wrong. A password with @, :, /, or % must be percent-encoded in the URL.

3. Is the backend pointing at the right host? Inside Docker Compose, the host in the URL is the service name (e.g. postgres), not localhost.

4. Firewall / network. If Postgres runs on another machine, confirm the port is reachable: nc -zv <host> 5432.

Symptom: "DATABASE_URL is not set" or "DATABASE_URL must name a database"Copy Anchor Link

The backend and worker stop at startup. Set DATABASE_URL in .env with a database name after the last /, for example postgresql://postgres:password@localhost:5432/tma_cloud_storage. The same check applies to REDIS_URL.

Encryption Key ErrorsCopy Anchor Link

Symptom: Backend or Worker Stops with "FILE_ENCRYPTION_KEY must be a random 32-byte key in production"Copy Anchor Link

The key is a passphrase. Production accepts only a random 32-byte key in base64 or hex.

1. Rotate to a random key. Run ./rotate.sh key on Docker, or tma-server rotate key. Both keep the passphrase as an older version so existing files still open. Replacing the key without rotating makes every stored file unreadable. See Key Rotation.

Symptom: "FILE_ENCRYPTION_KEY (key version N) does not match the key this deployment's data was encrypted with"Copy Anchor Link

The configured key differs from the one recorded in kek_checks.

1. Compare with your backup of the key. A copy-paste error or a trailing character is the usual cause.
2. Check the version prefixes. In a keyring each line is version:key, and a key without a prefix is version 1.
3. Check for both forms. FILE_ENCRYPTION_KEY and FILE_ENCRYPTION_KEY_FILE must not both be set.
4. The version is an older one? A line kept for older data is wrong. Restore it from the key file backup.

Symptom: "Stored data is encrypted under key version N, which FILE_ENCRYPTION_KEY does not contain"Copy Anchor Link

A key line that file keys or the bucket secret still use was removed, or an older key file was restored.

1. Restore the key file from the backup taken after the last rotation.
2. Check the version prefix of each line against the versions in the message.

Storage Bucket ErrorsCopy Anchor Link

Symptom: "Storage is not configured" (503 STORAGE_NOT_CONFIGURED)Copy Anchor Link

No bucket is saved. The first user connects one in Settings → Storage. See Storage Bucket.

Symptom: A Connection Check Fails When Saving the BucketCopy Anchor Link

The message names the failed check.

1. "Reach the bucket failed: Access denied" — Check the access key ID, the secret, and the key's permissions. Some providers, including RustFS, answer a missing bucket with the same 403.
2. "Could not connect to the endpoint" or "did not respond in time" — The backend container cannot reach the endpoint. The app image has no shell, so test from a throwaway container on the same network, for example docker run --rm --network tma-cloud_default curlimages/curl -sS -o /dev/null -w "%{http_code}\n" <endpoint> (the network is named after the install folder; docker network ls lists it). Any status code means the endpoint is reachable.
3. "The bucket is in a different region" — Set the bucket's region (Amazon S3).
4. "Find existing files failed" — The new bucket does not contain the files already stored. Copy the objects first.

Redis Connection ErrorsCopy Anchor Link

Symptom: "Redis connection failed"Copy Anchor Link

1. Is Redis running? redis-cli -u "$REDIS_URL" ping — should print PONG.
2. Auth enabled? If Redis requires a password, put it in REDIS_URL: redis://:password@host:6379/0.
3. Right host in Docker? Use the compose service name (redis), not localhost, as the host in REDIS_URL.

Storage Limit ErrorsCopy Anchor Link

Symptom: "Storage limit exceeded"Copy Anchor Link

1. Check the account's usage in Settings → Storage. If it's close to full, delete files or empty trash — trash counts toward quota.
2. Check provider limits. A full bucket quota or suspended provider account must be resolved with the storage provider.
3. Admin override. An admin can raise the limit for a specific user in Settings → Administration → Registered users.

Symptom: "This file is too large" on a Single UploadCopy Anchor Link

The file exceeds the per-request max upload size (separate from storage quota).

1. Raise the limit in Settings → Storage → Maximum upload size (first user only).
2. Reverse proxy limits. If you run nginx in front of the backend, client_max_body_size must also be raised — otherwise nginx rejects the request before it reaches the backend.
3. Split the file if you can't change the limits.

Upload ErrorsCopy Anchor Link

Symptom: "Upload failed" (Generic)Copy Anchor Link

1. Check bucket availability and provider quotas.
2. Check bucket credentials and policies — allow the backend to upload, read, list, and delete objects.
3. Network stability — retry once; transient drops cause this too.

See Upload Issues for upload-specific problems.

Authentication ErrorsCopy Anchor Link

Symptom: "Invalid credentials"Copy Anchor Link

1. Confirm email + password — passwords are case-sensitive.
2. Rate limit. After 25 attempts in 15 minutes from the same IP and email, further attempts are rejected until the window expires. Wait, or try from another network.

See Auth Issues for deeper auth troubleshooting.

Related TopicsCopy Anchor Link

• Auth Issues - Authentication problems
• Upload Issues - Upload problems
• API Errors - Error codes