Diagnosing and Fixing Harbor 2.x Project Quota Exceeded Errors

Problem Overview

The Harbor 2.x registry enforces per‑project limits on disk usage, image count, and tag count. When these limits are crossed, pushes to the project return a 422 Unprocessable Entity with a message like "Project quota exceeded". This article walks through a systematic diagnostic flow, identifies root causes, and shows concrete fixes tied to each finding.

Root Cause Table

Cause	Typical Symptoms	Primary Check
Storage quota reached	Push fails; UI shows storage near limit	Verify Storage metric vs. quota
Image count quota reached	Push fails; UI shows image count near limit	Compare Image Count metric to quota
Tag count quota reached	Push fails; UI shows tag count near limit	Check Tag Count metric vs. quota
Mis‑configured quota (typo or wrong unit)	Unexplained 422 even with low usage	Cross‑check UI and API quota values
Quota not enabled for project	Push succeeds but later fails after large push	Ensure Quota Enabled flag is true

Diagnostic Flow

1. Confirm the error: Push a small image to the project and note the exact error message.

   docker push myharbor.com/myproj/hello:latest
   # Expected: 422 Unprocessable Entity – Project quota exceeded

2. Check project metrics in the UI:
   • Navigate to Projects > myproj.
   • Note Storage, Image Count, and Tag Count values.
3. Retrieve the quota configuration via the REST API:

   curl -u admin:Harbor123! \
     -sS https://myharbor.com/api/v2.0/projects/myproj/quotas \
     | jq '.'
   # Example output:
   # {
   #   "storage_limit": 10737418240,  # 10 GB in bytes
   #   "image_count_limit": 1000,
   #   "tag_count_limit": 5000,
   #   "storage_used": 11234567890,
   #   "image_count_used": 1020,
   #   "tag_count_used": 5200
   # }

4. Match UI metrics against API values to rule out a display glitch.
5. Identify the specific quota breached by comparing *_used to *_limit.

Fixes Tied to Findings

1. Storage Quota Exceeded

• Delete unused repositories or tags. Use the API to target specific tags:

  curl -X DELETE -u admin:Harbor123! \
    -sS https://myharbor.com/api/v2.0/repositories/myrepo/tags/v1.0
  # Verify deletion via GET /repositories/{repo}/tags
  

• Increase the storage limit if the project legitimately needs more space:

  # Update via UI: Projects > myproj > Settings > Quota
  # Or API:
  curl -X PATCH -u admin:Harbor123! \
    -H "Content-Type: application/json" \
    -d '{"storage_limit": 21474836480}' \
    https://myharbor.com/api/v2.0/projects/myproj/quotas
  

2. Image Count Quota Exceeded

• Remove entire repositories that are no longer needed.
• Increase image_count_limit via UI or API as above.

3. Tag Count Quota Exceeded

• Delete obsolete tags with the API (see storage example).
• Consider enabling tag retention policies if Harbor 2.4+ supports them, to automatically prune old tags.

4. Mis‑configured Quota

• Double‑check the numeric values in the UI; Harbor accepts values in bytes for storage and plain integers for counts.
• Correct any typos via the API patch call.

Escalation Criteria

1. If the project is critical and cannot afford downtime, ask the storage team to increase the backend capacity before raising the quota.
2. If quota adjustments are blocked by policy, document the usage spike and request a temporary policy override.
3. When repeated pushes fail despite quota adjustments, verify that the registry backend (e.g., Ceph, S3) is not reporting its own limits.

Post‑Fix Verification

After any deletion or quota change, re‑attempt the push. The command should succeed and the UI metrics should reflect the new usage state. Use the API to fetch the updated *_used values and confirm they are below the limits.

Limitations & Precautions

• Always backup the registry before mass deletions to avoid accidental data loss.
• Increasing quotas may lead to higher storage costs and could strain the underlying storage backend.
• Disabling quotas on production projects is discouraged; use policy‑based retention instead.
• When deleting tags, target specific ones rather than entire repositories to preserve other images.