Troubleshooting

Use this page as a first pass before digging through source code.

Storage startup failure

Symptom

The API fails at startup with an S3 or bucket-health error.

Likely causes

• wrong STORAGE_ENDPOINT
• wrong STORAGE_BUCKET
• wrong STORAGE_ACCESS_KEY or STORAGE_SECRET_KEY
• bucket not created
• provider access denied

What to check

1. Confirm the bucket exists.
2. Confirm the endpoint is the provider’s S3-compatible endpoint, not a generic console URL.
3. Confirm the credentials have access to that bucket.
4. Recheck Storage Setup.

Backblaze browser upload CORS failure

Symptom

The app can issue presigned URLs, but the browser upload fails with a CORS error.

Root cause

The bucket CORS rules are missing or incomplete.

Fix

1. Add bucket CORS for the web app origin.
2. Allow the required methods such as PUT, GET, and HEAD.
3. Allow request headers such as content-type, or use * during initial validation.

This is not fixed by widening Fastify CORS.

Redis dashboard or Bull Board says you are not logged in

Symptom

You are logged into the app, but /admin/redis or /admin/queues rejects access.

Likely causes

• the route is being accessed through a different host than the logged-in app session
• the route is hitting the wrong service
• the user is not a SYSTEM_ADMIN

Fix

1. Prefer root-domain routing for /admin/redis and /admin/queues.
2. Confirm the route is proxied to the api service, not the web service.
3. Confirm the logged-in user has the SYSTEM_ADMIN role slug.

Root-domain /health, /documentation, or admin route returns SPA 404

Symptom

The browser shows the web app’s “Page Not Found” screen instead of an API response.

Root cause

The request is landing on the web app instead of the API service.

Fix

Add or correct reverse-proxy routes for:

• /api
• /admin/redis
• /admin/queues
• and any optional API-host routes you want

See Routing and Domains.

ArcLocale package install failure

Symptom

pnpm install or Docker source build fails while resolving @arc-laboratories/arclocale-compiler.

Likely causes

• a stale .npmrc is still forcing @arc-laboratories to GitHub Packages
• the lockfile still points at an older GitHub Packages tarball
• the dependency version was bumped without refreshing pnpm-lock.yaml
• minimumReleaseAge is still blocking a freshly published alpha

Fix

1. Remove any lingering @arc-laboratories registry override from .npmrc.
2. Refresh the lockfile with a new pnpm install after bumping the package version.
3. If you intentionally consume a just-published prerelease, confirm minimumReleaseAgeExclude includes that exact version.
4. Re-run the install after the lockfile points at the public npm release.

GHCR image pull failure

Symptom

Registry-image deployment fails to pull ghcr.io/arc-laboratories/... images.

Likely causes

• no docker login ghcr.io
• token lacks read:packages
• the image tag does not exist yet or is wrong

Fix

1. Authenticate with a credential that can pull from ghcr.io.
2. Confirm the image tag you are requesting actually exists.
3. If you do not want to manage GHCR auth on the target host, use the source-build path.

Infisical startup failure

Symptom

Containers fail before the app starts, often with missing Infisical token or project errors.

Likely causes

• INFISICAL_TOKEN-family variables missing
• INFISICAL_PROJECT_ID missing
• wrong INFISICAL_ENV
• using an Infisical-backed startup path without intending to

Fix

1. If you want Infisical, verify the bootstrap variables.
2. If you do not want Infisical on source/registry/manual paths, set SKIP_INFISICAL=true and provide the full runtime env directly.

Translation build fails even though deployment does not need API keys

Symptom

The web build fails in ArcLocale despite no translation-provider API key being configured.

Root cause

The deployment build is running in cache-only mode and required translation cache entries are missing.

Fix

1. Refresh or restore the committed translation cache.
2. Re-run the translation workflow if new strings were introduced.
3. Do not add translation-provider keys unless you intentionally want to run translation generation.

Postgres or Redis already exists but compose still fails

Symptom

The app stack does not come up cleanly even though you know the database or Redis server is available.

Likely causes

• compose-managed infra is using different credentials or DB names than expected
• the wrong .env file is loaded
• POSTGRES_DB or DATABASE_URL do not match the actual intended database

Fix

1. Re-check the compose file you are using.
2. Re-check .env against Environment Reference.
3. Confirm whether you are using bundled Postgres/Redis or external services.

Email looks configured, but no emails arrive

Likely causes

• sender domain not verified in Resend
• wrong RESEND_FROM_EMAIL
• REMOTE_EAZE_DISABLE_OUTBOUND_EMAIL=true

Fix

1. Confirm the sender domain is verified.
2. Confirm the sender email belongs to that domain.
3. Confirm outbound email disable mode is off when you expect live delivery.
4. Use pnpm email:test -- --list and a controlled send or dry-run preview.