Troubleshooting

Common installation problems and their fixes

install.sh stops at the registry step. The credentials are wrong or expired, or the server has no outbound HTTPS. Test with docker login <registry>; for a proxy set HTTPS_PROXY for the Docker daemon too (/etc/systemd/system/docker.service.d/proxy.conf).

migrate exits with an error. docker compose logs migrate. Usual causes: the database is not reachable (DATABASE_URL), the user cannot create extensions (CREATE EXTENSION vector needs a superuser once), or a half-applied earlier migration — restore the last backup and rerun.

The health check never passes. docker compose logs app. The first start loads catalogues and can take a few minutes on a slow disk; install.sh waits 4.5 minutes. If the log shows EACCES on /paperclip, the data directory is not writable by uid 1000: chown -R 1000:1000 /data-testingops/app.

Every request answers 503 "license_required". The installation has no valid license. Open the address in a browser and paste the token on the license screen, or put it at license/license.txt and docker compose restart app. GET /api/license shows the state; invalid with a reason means the token was edited, is for another product key, or the file is unreadable.

Browser shows the page but login fails / redirects loop. TESTINGOPS_PUBLIC_URL does not match the address in the browser (scheme, host or port). Fix it in env.list, docker compose up -d app.

403 "host not allowed". The request reached the application with a Host header different from the public URL — a load balancer rewrote it. Forward the original host, or add it to TESTINGOPS_ALLOWED_HOSTNAMES in env.list.

Runs never start. The execution engine is not configured or not reachable: Administration → Integrations → Test execution. The engine must be able to reach the application under test; the application under test must allow the engine's egress address.

Disk fills up. Evidence (videos, screenshots) lives under TESTINGOPS_DATA_DIR/app or in the S3 bucket. Retention is configurable per company; old images are pruned by upgrade.sh. docker system df shows what Docker itself holds.

Support bundle. docker compose logs --since 24h > logs.txt plus GET /api/health and the output of docker compose ps. Secrets are not in the logs; still review before sending.