Appearance
Troubleshooting
Use the error or symptom below to find the next action.
Convex admin key is not configured: set CONVEX_ADMIN_KEY
The API needs the full Convex admin key to start.
Run bash scripts/setup/open_core_up.sh to generate and deploy the key, or restore the existing full convex-self-hosted|... value in .env.
AUTH_API_KEY_PEPPER must be set to a deployment-specific secret when AUTH_MODE is not disabled
Authentication is enabled without a pepper.
Set a deployment-specific AUTH_API_KEY_PEPPER in .env and restart the API. Retain the value on upgrades.
API_CORS_ALLOWED_ORIGINS must list explicit origins
A wildcard origin is configured.
Replace it with a comma-separated list of exact web origins and restart the API.
401 UNAUTHORIZED or 403 FORBIDDEN
401 means the credential or session is missing or invalid; 403 means the authenticated principal lacks permission.
Sign in again or check the credential for 401. For 403, ask a workspace admin to check the role, project assignment and credential scopes.
UNKNOWN_RUN
The run has not been started in the target project.
Call POST /api/v1/runs/start before ingesting and use the returned run and project IDs.
409 CONFLICT with DELETED
The run, project or workspace was deleted and its ID is reserved.
Create a new target with a new ID.
Signed artifact URL fails
The public storage endpoint may be unreachable by the browser or SDK, or the URL may have expired.
Set OBJECT_STORAGE_PUBLIC_ENDPOINT to the client-reachable TLS storage origin, check the proxy and request a new URL.
Requested --web-port ... is already in use
Another process is listening on that port.
Stop that process or rerun setup with an available --web-port. Check other published ports if Compose reports a bind error.
[error] ClickHouse did not become ready on Colima
This happens when the checkout is outside your home directory. You may also see curl: (52) Empty reply from server and AUTHENTICATION_FAILED in the ClickHouse container logs.
Clone the repository under your home directory and run setup from that checkout.
DEV_MODE_REQUIRED
Authentication is disabled and dev mode is off.
Configure authentication for the deployment, or enable DEV_MODE only for local development.