Diagnosing Harbor 'ImagePullBackOff' and Unauthorized Access Errors

The Problem: Image Pull Failures

When a Kubernetes pod enters an ImagePullBackOff state or a Docker client returns 401 Unauthorized or 403 Forbidden, the issue is rarely a network failure. Most often, the failure stems from a mismatch between the Harbor project's visibility settings, the Robot Account's permission scope, or an expired authentication token.

Quick Diagnostic Matrix

Use this table to correlate the error message with the most likely root cause in Harbor.

Error Message	HTTP Code	Likely Cause	Primary Check
Unauthorized / 401	401	Expired Robot Token or Invalid Credentials	Robot Account Expiration Date
Forbidden / 403	403	Insufficient Permissions (RBAC)	Robot Account Project Scope
ImagePullBackOff (K8s)	Varies	Missing ImagePullSecret or Private Project	Project Visibility (Public vs Private)

Step-by-Step Resolution Path

1. Verify Project Visibility

Harbor projects are either Public (accessible without authentication) or Private (requires a valid token or user login). If a project was recently flipped from Public to Private, all unauthenticated pull requests will fail immediately.

• Navigate to Projects → [Project Name] in the Harbor UI.
• Check the Public toggle. If it is disabled, ensure your client is providing credentials.

2. Validate Robot Account Status

CI/CD pipelines should use Robot Accounts rather than administrator credentials to limit the blast radius of a credential leak. However, Robot Accounts have fixed expiration dates.

• Go to Projects → [Project Name] → Robot Accounts.
• Locate the account used by your pipeline. Check the Expiration column.
• If the token is expired, you must create a new Robot Account and update the secret in your deployment environment.

3. Audit Permission Scopes

A Robot Account may be active but lack the specific permission to pull images from the target repository.

• Verify that the Robot Account has the repository:pull permission assigned.
• Ensure the account is scoped to the specific project containing the image, or has system-wide access if pulling from multiple projects.

4. Test Client Authentication

To isolate the issue from Kubernetes or CI/CD orchestration, test the credentials directly from a terminal with Docker installed. Run this command as a user with permissions to modify the local Docker config:

# Replace [HARBOR_URL] and [ROBOT_ACCOUNT_NAME] with your actual values
# The password is the secret token provided during Robot Account creation
docker login [HARBOR_URL] -u [ROBOT_ACCOUNT_NAME]

Expected Result: A Login Succeeded message. If this fails with a 401, the token is invalid or expired. If this succeeds but Kubernetes still fails, the issue lies in the ImagePullSecret configuration within the cluster.

Configuration Example: Kubernetes ImagePullSecret

If docker login works but the pod still shows ImagePullBackOff, you must ensure the Kubernetes namespace has the correct secret to authenticate with Harbor.

# Run this on your local machine with kubectl configured
kubectl create secret docker-registry harbor-pull-secret \
  --docker-server=[HARBOR_URL] \
  --docker-username=[ROBOT_ACCOUNT_NAME] \
  --docker-password=[ROBOT_TOKEN] \
  --namespace=[TARGET_NAMESPACE]

Then, reference this secret in your deployment manifest:

spec:
  template:
    spec:
      imagePullSecrets:
        - name: harbor-pull-secret
      containers:
        - name: app-container
          image: [HARBOR_URL]/[PROJECT]/[IMAGE]:[TAG]

Limitations and Verification

Note that project quotas can occasionally interfere with metadata retrieval, though this typically affects push operations rather than pulls. To verify the fix, monitor the Harbor core service logs for the absence of 401/403 errors during the pull attempt.

Rollback Procedure

If changing a project from Private to Public causes security concerns, revert the setting immediately via the Harbor UI: Projects → [Project Name] → Toggle Public to Off. This will restore the requirement for authentication for all users.