Errors

Every Registry error carries a stable numeric error_code and a machine-readable reason. This page lists the logical error codes Registry can return, across its domain groups (9_3xx) and infrastructure groups (9_6xx). For the full error envelope (the google.rpc.Status shape, the reason and metadata fields, and how codes are structured) see Errors.

Registry codes begin with 9 (for example 9301001, read as 9_301_001: service, group, specific error). The wire value is always the flat integer; you can match on either error_code or reason, both are stable.

The Status column is the canonical gRPC status the error maps to, which the gateway renders as the matching HTTP status (see the status codes table).

Code	Reason	Status	Description
9301001	REPOSITORY_NOT_FOUND	NOT_FOUND	Repository not found.
9301002	REPOSITORY_ALREADY_EXISTS	ALREADY_EXISTS	A repository with this name already exists in the workspace.
9301003	REPOSITORY_NAME_VALIDATION	INVALID_ARGUMENT	Repository name is not valid.
9301004	REPOSITORY_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Repository workspace ID is required.
9301005	REPOSITORY_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Repository must be marked for deletion before removal.
9301006	REPOSITORY_VISIBILITY_NOT_VALID	INVALID_ARGUMENT	Repository visibility is not valid.
9301007	REPOSITORY_FORMAT_NOT_VALID	INVALID_ARGUMENT	Repository format is not valid.
9301008	IMAGE_REPOSITORY_DESCRIPTION_NOT_VALID	INVALID_ARGUMENT	ImageRepository description must be at most 1024 characters and carry no control or bidirectional characters.
9302001	REGISTRY_OPERATION_NOT_FOUND	NOT_FOUND	Registry operation not found.
9302002	REGISTRY_OPERATION_PROGRESS_OUT_OF_RANGE	INVALID_ARGUMENT	Operation progress must be between 0 and 100.
9302003	REGISTRY_OPERATION_END_TIME_BEFORE_START_TIME	INVALID_ARGUMENT	Operation end time must not be before start time.
9302006	REGISTRY_OPERATION_SCOPE_TYPE_NOT_VALID	INVALID_ARGUMENT	Operation scope type is not valid.
9303001	ACCESS_POLICY_NOT_FOUND	NOT_FOUND	Access policy not found.
9303002	ACCESS_POLICY_ALREADY_EXISTS	ALREADY_EXISTS	An access policy already exists for this principal and scope.
9303003	ACCESS_POLICY_SCOPE_NOT_VALID	INVALID_ARGUMENT	Access policy scope ID is required.
9303004	ACCESS_POLICY_PRINCIPAL_ID_NOT_VALID	INVALID_ARGUMENT	Access policy principal ID is required.
9303005	ACCESS_POLICY_ACTIONS_ARE_EMPTY	INVALID_ARGUMENT	Access policy must have at least one action.
9303006	ACCESS_POLICY_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Access policy must be marked for deletion before removal.
9303007	ACCESS_POLICY_PRINCIPAL_TYPE_NOT_VALID	INVALID_ARGUMENT	Access policy principal type is required.
9303008	ACCESS_POLICY_ACTION_NOT_VALID	INVALID_ARGUMENT	Access policy action is not valid.
9304001	SCAN_POLICY_NOT_FOUND	NOT_FOUND	Scan policy not found.
9304002	SCAN_POLICY_ALREADY_EXISTS	ALREADY_EXISTS	A scan policy already exists for this scope.
9304003	SCAN_POLICY_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Scan policy scope ID is required.
9304004	SCAN_POLICY_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Scan policy scope type is not valid.
9305001	RETENTION_POLICY_NOT_FOUND	NOT_FOUND	Retention policy not found.
9305002	RETENTION_POLICY_ALREADY_EXISTS	ALREADY_EXISTS	A retention policy already exists for this repository.
9305003	RETENTION_POLICY_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Retention policy repository ID is required.
9305004	RETENTION_POLICY_SCHEDULE_NOT_VALID	INVALID_ARGUMENT	Retention policy schedule is not valid.
9305005	RETENTION_POLICY_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Retention policy must be marked for deletion before removal.
9305006	RETENTION_RULE_NOT_SPECIFIED	INVALID_ARGUMENT	Each retention rule must specify exactly one keep rule.
9306001	DEPLOYMENT_LOCK_NOT_FOUND	NOT_FOUND	Deployment lock not found.
9306002	DEPLOYMENT_LOCK_ALREADY_EXISTS	ALREADY_EXISTS	A deployment lock already exists for this digest and context.
9306003	DEPLOYMENT_LOCK_REPOSITORY_ID_NOT_VALID	INVALID_ARGUMENT	Deployment lock repository ID is required.
9306004	DEPLOYMENT_LOCK_DIGEST_NOT_VALID	INVALID_ARGUMENT	Deployment lock digest is not valid.
9306005	DEPLOYMENT_LOCK_ACTIVE	FAILED_PRECONDITION	Cannot delete an image while deployment locks are active.
9306006	DEPLOYMENT_LOCK_CONTEXT_NOT_VALID	INVALID_ARGUMENT	Deployment lock context is not valid.
9306007	DEPLOYMENT_LOCK_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Deployment lock must be marked for deletion before removal.
9307001	WORKSPACE_REGISTRY_NOT_FOUND	NOT_FOUND	The workspace has no registry.
9307002	WORKSPACE_REGISTRY_WORKSPACE_ID_NOT_VALID	INVALID_ARGUMENT	Workspace registry workspace ID is required.
9307003	WORKSPACE_REGISTRY_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Workspace registry must be marked for deletion before removal.
9309001	ARTIFACT_NOT_FOUND	NOT_FOUND	Artifact not found.
9309002	ARTIFACT_DELETION_FAILED	UNAVAILABLE	Failed to delete the artifact in the registry backend.
9309003	ARTIFACT_LOOKUP_FAILED	UNAVAILABLE	Failed to resolve the artifact in the registry backend.
9310001	TAG_DELETION_FAILED	UNAVAILABLE	Failed to delete the tag in the registry backend.
9311001	SCAN_TRIGGER_FAILED	UNAVAILABLE	Failed to trigger the artifact scan in the registry backend.
9312001	REPOSITORY_NAME_PATTERN_NOT_VALID	INVALID_ARGUMENT	Repository name pattern is not valid.
9313001	QUOTA_DEFINITION_METRIC_IS_BLANK	INVALID_ARGUMENT	Quota definition metric is required.
9313002	QUOTA_DEFINITION_METRIC_FORMAT_IS_NOT_VALID	INVALID_ARGUMENT	Quota definition metric format is not valid.
9313003	QUOTA_DEFINITION_DISPLAY_NAME_IS_BLANK	INVALID_ARGUMENT	Quota definition display name is required.
9313004	QUOTA_DEFINITION_DEFAULT_LIMIT_IS_NOT_VALID	INVALID_ARGUMENT	Quota definition default limit is not valid.
9313005	QUOTA_DEFINITION_REFRESH_INTERVAL_IS_NOT_VALID	INVALID_ARGUMENT	Quota definition refresh interval is not valid.
9313006	QUOTA_DEFINITION_NOT_FOUND	NOT_FOUND	Quota definition not found.
9314001	QUOTA_LIMIT_EFFECTIVE_LIMIT_IS_NOT_VALID	INVALID_ARGUMENT	Quota limit effective limit is not valid.
9314002	QUOTA_LIMIT_SCOPE_ID_IS_NOT_VALID	INVALID_ARGUMENT	Quota limit scope ID is not valid.
9314003	QUOTA_LIMIT_NOT_FOUND	NOT_FOUND	Quota limit not found.
9314004	QUOTA_LIMIT_ALREADY_EXISTS	ALREADY_EXISTS	A quota limit already exists for this scope and metric.
9314005	QUOTA_LIMIT_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Quota limit must be marked for deletion before removal.
9315001	GRANT_TARGET_NOT_VALID	INVALID_ARGUMENT	Cross-workspace pull grant target is not valid.
9315002	GRANT_SOURCE_AND_TARGET_SAME	INVALID_ARGUMENT	Cross-workspace pull grant source and target must be different.
9315003	GRANT_NOT_FOUND	NOT_FOUND	Cross-workspace pull grant not found.
9315004	GRANT_ALREADY_EXISTS	ALREADY_EXISTS	A cross-workspace pull grant already exists for this source, target, and tag pattern.
9315005	GRANT_NOT_MARKED_FOR_DELETION	FAILED_PRECONDITION	Cross-workspace pull grant must be marked for deletion before removal.
9316001	OCI_TOKEN_NOT_VALID	UNAUTHENTICATED	The presented registry bearer token could not be verified.
9317001	OCI_DIGEST_NOT_VALID	INVALID_ARGUMENT	The digest is not well formed.
9317002	OCI_DIGEST_ALGORITHM_NOT_SUPPORTED	INVALID_ARGUMENT	The digest algorithm is not supported.
9318001	OCI_MANIFEST_SIZE_NOT_VALID	INVALID_ARGUMENT	The manifest exceeds the 4 MiB ceiling.
9318002	OCI_MANIFEST_ALREADY_EXISTS	ALREADY_EXISTS	A manifest with this digest already exists in the repository.
9318003	OCI_MANIFEST_DIGEST_NOT_VALID	INVALID_ARGUMENT	The manifest digest is not valid.
9318004	OCI_MANIFEST_UNKNOWN	NOT_FOUND	No manifest under that tag or digest that this client can be served.
9319001	OCI_TAG_NAME_NOT_VALID	INVALID_ARGUMENT	The tag name is not valid.
9320001	OCI_BLOB_STATE_TRANSITION_NOT_VALID	FAILED_PRECONDITION	The OCI blob cannot move to the requested storage state.
9320002	OCI_BLOB_SIZE_NOT_VALID	INVALID_ARGUMENT	The OCI blob size is not valid.
9320003	OCI_BLOB_OBJECT_NAME_NOT_VALID	INVALID_ARGUMENT	The OCI blob object name is required.
9320004	OCI_BLOB_UNKNOWN	NOT_FOUND	The repository does not hold a blob with this digest.
9320005	OCI_BLOB_RANGE_NOT_SATISFIABLE	INVALID_ARGUMENT	The requested byte range names no byte the OCI blob holds.
9321001	OCI_REPOSITORY_REFERENCE_NOT_RESOLVABLE	NOT_FOUND	The OCI repository reference could not be resolved.
9322001	WORKSPACE_STATE_NOT_RECOGNISED	FAILED_PRECONDITION	The workspace lifecycle state reported by taxonomy is not recognised.
9324001	OCI_FIXTURE_LAYOUT_NOT_READABLE	FAILED_PRECONDITION	The OCI fixture layout could not be read.
9324002	OCI_FIXTURE_IMAGE_NOT_NAMED	FAILED_PRECONDITION	The OCI fixture layout names no image to import.
9324003	OCI_FIXTURE_DOCUMENT_NOT_AVAILABLE	FAILED_PRECONDITION	The OCI fixture layout holds no document at the address referenced.
9325001	OCI_SCOPE_NOT_VALID	INVALID_ARGUMENT	The OCI scope is not valid.
9605001	UNKNOWN_SCHEMA_VERSION	DATA_LOSS	Schema version is not recognized.
9605002	REGISTRY_OPERATION_NOT_FOUND	NOT_FOUND	The registry operation was not found.
9605003	UNKNOWN_REGISTRY_OPERATION_RESOURCE_TYPE	DATA_LOSS	The registry operation resource type is not recognized.
9605004	CREDENTIAL_RECORD_MISSING_EXPIRY	DATA_LOSS	The credential record is missing its required expiry timestamp.
9606001	UNKNOWN_INTEGRATION_VERSION	INVALID_ARGUMENT	The integration version is not recognized.
9606002	UNKNOWN_TAXONOMY_EVENT	INVALID_ARGUMENT	The taxonomy event type is not recognized.
9606003	UNKNOWN_MESSAGE_TYPE	INVALID_ARGUMENT	The consumed message type is not recognized.
9606004	UNKNOWN_IAM_EVENT	INVALID_ARGUMENT	The iam event type is not recognized.
9606005	UNSUPPORTED_DATA_UNIT	INVALID_ARGUMENT	The registry data unit is not supported.
9607001	HARBOR_UNSUPPORTED_FILTER_FIELD	INVALID_ARGUMENT	Filter field is not supported by Harbor.
9607002	HARBOR_UNSUPPORTED_FILTER_OPERATOR	INVALID_ARGUMENT	Filter operator is not supported by Harbor.
9607003	HARBOR_UNSUPPORTED_FILTER_EXPRESSION	INVALID_ARGUMENT	Filter expression type is not supported by Harbor.
9607005	HARBOR_UNREACHABLE	UNAVAILABLE	Harbor is unreachable.
9607006	HARBOR_PERMISSION_DENIED	PERMISSION_DENIED	Harbor rejected the request (permission denied).
9607007	HARBOR_UNAVAILABLE	UNAVAILABLE	Harbor is temporarily unavailable.
9607008	HARBOR_PROJECT_OPERATION_FAILED	UNAVAILABLE	Harbor project operation failed.
9607009	HARBOR_INVALID_TIMESTAMP	DATA_LOSS	Harbor returned a timestamp the adapter cannot read.
9607010	HARBOR_RESOURCE_NOT_FOUND	NOT_FOUND	Harbor does not have the requested resource.
9607011	HARBOR_RESOURCE_ALREADY_EXISTS	ALREADY_EXISTS	Harbor already has the requested resource.
9607012	HARBOR_REQUEST_REJECTED	INVALID_ARGUMENT	Harbor rejected the request.
9607013	HARBOR_REQUEST_TIMED_OUT	DEADLINE_EXCEEDED	Harbor did not answer within the request deadline.
9608001	QUOTA_EXCEEDED	RESOURCE_EXHAUSTED	Registry storage quota exceeded.
9608002	SCAN_NOT_AVAILABLE	FAILED_PRECONDITION	Artifact scan report is not yet available.
9610001	TOKEN_REALM_URL_NOT_CONFIGURED	FAILED_PRECONDITION	registry.oci.token-realm-url must be a non-blank URL: it is the only address a client is ever given for the token endpoint.
9610002	HOSTNAME_NOT_CONFIGURED	FAILED_PRECONDITION	registry.oci.hostname must be non-blank: it names the service in every bearer challenge and appears in every image reference users type.
9610003	TOKEN_PUBLIC_KEY_NOT_CONFIGURED	FAILED_PRECONDITION	registry.oci.token-public-key must be a non-blank PEM public key: it is the only thing distinguishing a token this platform issued from one an attacker signed.

Data-plane errors look different

The codes above are the control-plane (gRPC) errors. Image pull requests go through the OCI Distribution data plane, which has its own error envelope defined by the specification — UNAUTHORIZED, DENIED, NAME_UNKNOWN, MANIFEST_UNKNOWN, BLOB_UNKNOWN, DIGEST_INVALID, UNSUPPORTED — and does not carry a numeric error_code. See Pulling images.

The 93170xx, 93180xx and 93190xx rows above name the same conditions, but they are internal codes: the pull path translates each one into the bare envelope before it reaches the wire, so a client that sees MANIFEST_UNKNOWN never also sees 9318004. Match on the envelope’s code for a pull, and on error_code or reason everywhere else.

Codes that reach you on an operation, not on a call

These never appear as the status of a request. They record why a long-running operation did not finish, so they arrive in the operation record’s errors list while the call that started it succeeded.

Code	Reason	Description
9302004	ARTIFACT_SCAN_FAILED	The vulnerability scanner failed to complete the scan.
9302005	ARTIFACT_SCAN_TIMED_OUT	The vulnerability scan did not complete within the scan timeout.
9323001	OCI_FIXTURE_BLOB_BYTES_NOT_WRITTEN	The fixture blob’s bytes were not written to storage.

Codes that are reported, not returned

None of these is ever a request’s error_code. They say why something further down refused, and they surface in one of two places: the errors list of an operation record, or the detail of the error actually returned, written as code:reason. Read them as the cause behind the status you were given.

Code	Reason	Description
9302004	ARTIFACT_SCAN_FAILED	The vulnerability scanner failed to complete the scan.
9302005	ARTIFACT_SCAN_TIMED_OUT	The vulnerability scan did not complete within the scan timeout.
9323001	OCI_FIXTURE_BLOB_BYTES_NOT_WRITTEN	The fixture blob’s bytes were not written to storage.
9609001	REGISTRY_BUCKET_NOT_ENSURED	The workspace’s managed registry bucket could not be ensured.