Troubleshooting Artifact Registry

When working with Artifact Registry, you might encounter the following issues. Every response carries an X-Request-ID header. Include that value when you report a problem.

401 Unauthorized when you publish or pull

Four different causes return this same response: a missing credential, an empty credential, a malformed credential, and a credential that does not match. The response is deliberately identical in each case, so it reveals nothing about which cause applies.

The most common cause is an expired token. Artifact Registry tokens are short-lived.

To resolve this issue, get a fresh token and update your client configuration. To confirm the configuration matches, select More actions ( ) > View setup instructions on the repository.

For npm, check that the registry line and the authentication line carry the same URL, including the trailing slash. npm matches the authentication line by URL prefix, so a mismatch returns 401 without naming the URL.

For Maven, check that the server id in your settings file matches the id on the repository you deploy to. If the two id values differ, Maven sends no credentials at all.

409 Conflict when you request a token

The exchange returns 409 Conflict when your account belongs to more than one organization that has Artifact Registry. The response is Your account belongs to more than one organization with Artifact Registry. This is not supported yet.

The exchange works out which organization to use from your memberships. It cannot pick between two organizations, so it refuses instead of guessing.

There is no workaround in beta. If you hit this issue, contact your GitLab account team.

404 Not Found when you request a token

Token exchange runs behind a feature flag named gate_token_exchange_endpoint. The flag is disabled by default. When the flag is off, POST /api/v4/token_exchange returns 404. The response says nothing about the flag.

The endpoint needs GitLab 19.1 or later, Enterprise Edition.

To resolve this issue, ask an administrator to enable the flag for your instance. On GitLab.com, contact your GitLab account team instead, because Artifact Registry is invitation-only in beta. For more information, see feature flags.

404 Not Found for a repository you know exists

You might not have a role on the repository. Artifact Registry returns 404 rather than 403 when you cannot read a resource, so a repository you cannot access looks the same as one that does not exist. Repositories you cannot read are also left out of lists silently.

To resolve this issue, ask an Artifact Admin to assign you a role. A role change is not immediate. It can take a minute or more to take effect. During that window, the same request can succeed and then fail again, so one 200 response does not mean the change is done. Retry for a few minutes before you conclude the role was not assigned.

403 Forbidden when you publish or delete

You can read the repository, but your role does not hold the permission for that action.

Publishing needs the Artifact Contributor role or higher. Deleting artifacts needs the Artifact Manager role or higher.

An empty repository list

A user with no assigned role sees an empty list rather than an error.

To resolve this issue, ask an Artifact Admin for a role.

409 Conflict when you delete a repository

A delete request with destructive=false refuses to touch contents, so a repository that still holds artifacts returns 409.

To resolve this issue, resend the request with destructive=true, which deletes the repository and its contents.

For a hosted container repository, emptying it through its /v2/ delete commands does not clear the 409. Those commands leave behind the row the delete conflicts with. Use destructive=true instead. This behavior is tracked in issue 371.

For a hosted npm repository, unpublish commands mark packages for removal rather than removing them at once, so the 409 stands until the removal finishes. Retry the delete after the removal completes.

500 when you delete a virtual repository

Deleting a virtual repository fails under either destructive value, whether or not the repository is empty. This behavior is tracked in issue 819.

409 Conflict when you delete a container manifest

Another manifest references the manifest you are deleting. The response lists the manifests that reference it.

To resolve this issue, delete the referencing manifests first.

503 Service Unavailable from a remote repository

The upstream is marked unhealthy after three consecutive failures. A Retry-After header tells you when to try again. A read that the cache can serve still succeeds even while the upstream is unhealthy.

To resolve this issue, test the upstream connection and check the upstream URL and credentials. A 401, 403, or 404 response from an upstream counts as healthy, because it proves the upstream is reachable.

400 MANIFEST_INVALID when you push to a Docker repository

A Docker repository accepts image manifests and manifests that carry a subject. It rejects an artifact that is neither, such as a Helm chart or a WebAssembly module with an empty configuration. Docker manifest schema 1 is also rejected.

To resolve this issue, push to an Open Container Initiative (OCI) format repository instead. The format is fixed when you create the repository, so you must create a new repository.

422 with name, format, and kind are immutable

You tried to change a property that is fixed when the repository is created.

To resolve this issue, create a new repository. Only the description can change after creation.

A path length error when you push a container image

The full path, including the registry handle, the repository name, and the image name, cannot be longer than 255 characters. Separator characters count toward this limit.

To resolve this issue, use shorter names.

Usage figures that do not match

Some figures are stored counters that update in the background, and others are counted at the moment you ask, so two figures over the same content can disagree for a short time.

For what each figure counts and why they differ, see View storage usage.