Troubleshooting

License invalid or expired

Licenses expire after 30 days. Symptoms: the backend rejects the license or LLM calls fail authentication.

1. Open the cabinet at https://app.copul4.com.

2. Renew or regenerate the license.

3. Update LICENSE_TOKEN in the backend .env (/root/copula/.env for provisioned installs; for manual installs the .env next to your docker-compose.yml) and restart the backend:

   docker compose up -d

Quota exhausted — HTTP 429 copula_quota_exceeded

The cabinet LLM router enforces a five-hour and a weekly (Monday 00:00 UTC start) fixed UTC window. When a window is exhausted, requests return 429 with code copula_quota_exceeded.

• Wait for the window to reset, or
• upgrade the tariff (base_x1 → base_x5 → base_x10 → pro) in the cabinet.

Migration failure

The copula-migrate init job applies migrations before the backend starts. If it fails, the backend never starts.

docker logs copula-migrate

Fix the reported problem (usually database connectivity or credentials in .env) and re-run docker compose up -d.

Backend unhealthy

docker logs copula-back

Verify the .env values against the environment variable reference — most startup failures are a missing or malformed JWT_SECRET (must be exactly 128 hex characters), ENCRYPTION_KEY (32 characters), or LICENSE_TOKEN.

Caddy certificate failure (provisioned installs)

If copula-caddy cannot obtain a certificate:

1. Check that the domain's DNS has propagated and resolves to the server's public IP.
2. Check that ports 80 and 443 are free and reachable from the internet — Caddy is the only service that should publish them, and the Let's Encrypt HTTP-01 challenge needs port 80.

Final health probe fails on a healthy install

If the deploy's await_health step fails but the stack is actually running, the likely cause is hairpin NAT: the server cannot reach its own public domain from inside. Verify the backend directly:

docker logs copula-back
curl http://127.0.0.1:8901

The installation is usable; access it through the domain from outside.

Failed self-update

There is no automatic rollback. A failed container swap leaves the previous container stopped under a renamed predecessor name.

1. List the containers to find the renamed predecessor:

   docker ps -a

2. Rename it back and start it:

   docker rename <renamed-predecessor> copula-back
   docker start copula-back

3. Retry the update later, or update manually with docker compose pull && docker compose up -d (see Updating).

Self-update or code search does nothing

The backend container must have /var/run/docker.sock mounted. Both self-update and the cocoindex integration depend on it. Check the volume list of copula-back in docker-compose.yml and recreate the stack if the mount is missing.