Start here when something does not work. Find the symptom, then the cause. Commands assume Docker Compose in /opt/dpndncy; on Kubernetes use kubectl logs and kubectl describe.
#First, three commands
curl -sS https://<api address>/health # is it running, and which version
docker compose ps # are both containers up and healthy
docker compose logs --tail 100 dpndncY # what the application says (JSON lines)
#It will not start
| Symptom |
Cause |
Fix |
Container restarts at once; log says CORS_ORIGIN missing in production |
The console address is not configured |
Set CORS_ORIGIN to the console address. Compose and Helm derive it from DOMAIN / config.publicUrl |
Log says APP_SECRET env var missing in production |
No APP_SECRET |
Set it (openssl rand -hex 32) |
helm install stops with "Set config.publicUrl" |
The chart needs the console address |
Set config.publicUrl, or enable the ingress with a host |
Container exits straight after start with Express exited before becoming ready |
The API failed to start; the line before it says why |
Read the log above that line |
docker compose up says set DOMAIN in .env |
A required value is missing |
Fill in DOMAIN and API_DOMAIN in .env |
Pod Pending |
No volume could be created |
kubectl get pvc -n dpndncy; fix the StorageClass |
| Container is killed for memory |
The limit is too low for the scan |
Raise the memory limit (4 GB or more) |
#I cannot reach it
| Symptom |
Cause |
Fix |
| Browser cannot connect |
DNS does not point at the machine, or port 443 is closed |
Check the name resolves, and the firewall and security group |
| Browser warns about the certificate |
Not issued yet, or an internal authority the browser does not trust |
Wait a minute and check docker compose logs caddy. Both names must resolve here and ports 80 and 443 must be open. For an internal authority, distribute its root certificate |
502 Bad Gateway |
The proxy is up but the application is not (yet) |
Wait for the application to become healthy, or read its log |
Console works, the CLI gets 404 |
The CLI is pointed at the console address |
Use the API address. See Ports and networking |
| CLI exits 5 |
Cannot connect: wrong address, blocked by a firewall, or an untrusted certificate |
curl the API /health from the runner. For a private certificate authority set NODE_EXTRA_CA_CERTS |
curl https://<api>/health works, pipelines still cannot connect |
The runner is behind a proxy |
Set HTTPS_PROXY on the runner |
#Signing in
| Symptom |
Cause |
Fix |
| "The request could not be verified" |
The address in the browser is not the configured console address |
Browse to exactly the address in CORS_ORIGIN / NEXT_PUBLIC_APP_ORIGIN: same scheme, name and port |
| Sign-in works, then you are signed out on the next click |
Secure cookies over plain HTTP |
Use HTTPS. For a test over HTTP only, COOKIE_SECURE=false |
| Everyone is signed out after a restart |
Expected: browser sessions end when the server restarts |
Sign in again. API tokens are not affected |
| "Too many sign-in attempts" |
The sign-in rate limit (20 per 15 minutes per address) |
Wait. Behind a proxy make sure TRUST_PROXY=true, or everyone shares one address |
| The operator password stopped working after a restart |
ENABLE_BOOTSTRAP_SUPERADMIN is still true, which resets it at every start |
Sign in with the configured password, change it, set the flag to false |
| "Tenant membership is required" with single sign-on |
The person is not a member of any tenant |
Add them under Settings, Users |
| Two-step verification locked someone out |
Lost device |
A tenant owner resets it for them under Settings, Users |
#Scans
| Symptom |
Cause |
Fix |
| CLI exit 4 |
Token invalid or expired, or its user is not an analyst |
Create a new token for a user with the analyst role |
| CLI exit 1 with "scan policy" |
The scan broke the tenant's policy |
Read the violations in the result. Fix, or adjust the policy |
Everything lands in one project named source or workspace |
The CI checkout folder has a meaningless name |
Pass --project <name> or set DPNDNCY_PROJECT |
| Upload refused as too large |
The archive exceeds MAX_ZIP_UPLOAD_MB, or a proxy body limit |
Exclude build output with a .dpndncyignore file, or raise the limits |
| Scans stop after about a minute |
A proxy or load balancer timeout |
Raise the read timeout on the API name to 600 seconds |
| No vulnerabilities found for a project that has them |
A lockfile is missing, so versions are unknown |
Commit the lockfile. Some ecosystems need one |
| Scans fail with network errors |
Outbound access is blocked |
Allow the destinations in Ports and networking, or configure a proxy |
| The queue keeps growing |
Too many concurrent scans for the machine |
Settings, System health. Give the machine more CPU and memory |
| "The installation is read-only" |
The trial or licence ended |
Apply a licence under Settings, License |
#Data and upgrades
| Symptom |
Cause |
Fix |
| History is gone after replacing the container |
The data volume was not mounted at /app/data |
Mount the volume exactly there. Restore from a backup if it was lost |
| Stored git tokens or integrations stopped working |
APP_SECRET was changed without re-encrypting |
Put the old value back, or run the rotation tool (Running dpndncY) |
| Upgrade failed part-way |
A migration did not finish |
Restore the backup you took before upgrading, with the previous image version |
| Disk is filling |
Scan history and logs |
Check the volume size. Docker logs rotate at 10 MB x 5 files. Audit logs are kept 90 days (AUDIT_LOG_RETENTION_DAYS) |
docker compose ps
docker compose logs --tail 300 dpndncY > dpndncy.log
curl -sS https://<api address>/health
Send the version, what you expected, what happened, the CLI exit code if relevant, and dpndncy.log. Remove anything you do not want to share: logs do not contain passwords or tokens, but they do contain project names and addresses.
