Troubleshooting

401 Unauthorized

Cause: Invalid client credentials, or the client has expired.

Fix:

1. Verify the client ID and password are correct
2. Check the client’s expiration date in the portal. Expired clients always return 401
3. Confirm you are sending HTTP Basic Auth (not a bearer token)

# Test authentication manually
curl -v -u client-id:password http://drevnix.company.com:8000/v2/

403 Forbidden

Cause: The client authenticated successfully but has no permission matching the requested repository.

Fix:

1. In the portal, go to Clients → select the client → view its permissions
2. Check whether any permission pattern covers the repository being pulled
3. Remember: wildcards only work at the end. ghcr/myorg/* is valid, ghcr/*/api is not
4. Add a permission if one is missing

404 Not Found

Cause: The upstream ID in the pull URL does not exist in Drevnix.

Fix:

1. Check your pull URL format: drevnix-host:8000/<upstream-id>/<repo>:<tag>
2. Verify the upstream ID exists in the portal under Upstreams
3. IDs are case-sensitive

docker login fails

Symptom: Error response from daemon: Get "https://drevnix.company.com/v2/": ...

Fix:

1. Confirm the proxy port is reachable: curl -v http://drevnix.company.com:8000/v2/
2. If using HTTPS, verify the TLS certificate is valid and trusted
3. If using HTTP for local development only, add the host to Docker’s insecure registries:

// /etc/docker/daemon.json
{"insecure-registries": ["drevnix.company.com:8000"]}

Then restart the Docker daemon.

Cache not working

Symptom: Pulls are still slow; no entries appear in the portal Cache page.

Fix:

1. Confirm CACHE_ENABLED=true is set and the container was restarted after adding it
2. Confirm CACHE_DIR exists and is writable
3. The admission policy requires a blob to be pulled at least 3 times within 10 minutes (or 10 times within 1 hour) before it is cached. Pull the same image multiple times to trigger caching
4. Check the portal Cache page for disk usage and entry count

Database connection issues

Symptom: Drevnix fails to start; logs show a JDBC connection error.

Fix:

1. Confirm PostgreSQL is running and reachable from the Drevnix container
2. Check JDBC_URL is correct. Credentials are embedded in the URL (e.g. jdbc:postgresql://user:password@host:5432/drevnix)
3. Test the connection: psql -h host -U username -d drevnix

Slow pulls

Cause: Cache miss on first pull, or admission threshold not yet met.

Fix:

1. Enable the blob cache. Subsequent pulls of the same layer will be served from disk
2. If cache is enabled but pulls are still slow, the admission threshold may not be met yet. Try lowering CACHE_MIN_HITS_SHORT to 1 temporarily
3. Check network connectivity to the upstream registry from the Drevnix host

Lost admin access

If all super-admin portal accounts are locked out, run init-admin to create a new super-admin account:

docker exec -it drevnix java -jar /opt/drevnix.jar init-admin --config=/etc/drevnix/config.edn

This does not remove existing accounts. It just adds a new one.

Checking logs

docker logs drevnix --tail 100 -f

Look for ERROR and WARN level entries. Most issues are surfaced clearly in the logs on startup or on the failing request.