Harbor troubleshooting

docker login fails / unauthorized

Wrong credentials, expired robot token, or user lacks project access. Verify username format for robots: robot$project+name. Check project membership in the UI. For LDAP/OIDC, confirm identity provider sync. TLS: self-signed cert needs CA in Docker (/etc/docker/certs.d/harbor.example.com/ca.crt) or insecure-registries (dev only).

denied: requested access to the resource is denied

Push to a project without Developer+ role, wrong project name in path, or immutable tag / retention policy blocking overwrite. Robot account needs push permission on that repository. Pull denied may be vulnerability policy blocking images above severity threshold — check scan results in the UI.

ImagePullBackOff in Kubernetes

Wrong image path, missing imagePullSecrets, or node cannot reach Harbor. Verify: kubectl describe pod Events. Test from node: crictl pull harbor.example.com/project/app:tag. Create docker-registry secret with robot credentials. HTTP registry on HTTPS-only cluster needs insecure registry config on container runtime.

Push succeeds but UI shows no image

Pushed to wrong project or registry hostname. Confirm tag matches harbor.host/PROJECT/REPO:tag. Refresh project repositories. Check core and registry logs if API errors. Replication may have moved artifact to another Harbor — check replication jobs.

Disk full / registry storage growing

Layers accumulate; deleting tags does not free space until garbage collection runs. Schedule GC in Administration → Clean up. Add retention policies to limit old tags. Check blob storage path in harbor.yml (data_volume or S3). See disk volumes lab.

Vulnerability scan stuck or failed

Trivy adapter down or cannot reach scanner. Check scanner container logs and jobservice for scan job errors. Air-gapped installs need offline vulnerability DB updates. Large images timeout — increase job timeout in config.

Replication failing

Check replication execution logs in the UI. Causes: destination credentials, firewall, tag filter mismatch, or destination project does not exist. For Docker Hub rate limits, use Harbor proxy cache project instead of direct hub pull.

502 / 503 from Harbor UI or API

Core service cannot reach Postgres or Redis. Check docker compose ps — all containers healthy. Verify harbor.yml database credentials. Postgres connection exhaustion — restart core after DB recovery. Reverse proxy misconfiguration if only external access fails.

Debugging workflow

1. Health and login

curl -sk https://harbor.example.com/api/v2.0/health
docker login harbor.example.com

2. Push/pull test

docker pull alpine
docker tag alpine harbor.example.com/library/alpine:test
docker push harbor.example.com/library/alpine:test

3. Component logs

docker compose logs --tail=50 core registry jobservice
# K8s Helm deploy: kubectl logs -n harbor -l component=core

Practice scenarios

Hands-on Harbor scenarios on live Linux VMs: harbor

Cheatsheet →