Troubleshoot Artifact Registry
This feature is in Beta. To use it, a workspace admin must turn on Databricks Artifact Registry from the Previews page. See Manage Databricks previews. Databricks will announce pricing for Artifact Registry when it becomes generally available.
Use this page to resolve common issues with Artifact Registry. For the complete setup and image push workflow, see Get started with Artifact Registry.
Beta access issues
Artifact Registry is not enabled
Ask a workspace admin to enable Databricks Artifact Registry on the workspace Previews page. If the preview is not available, verify that the workspace is in a region that supports Artifact Registry. See Limitations.
Preview status is temporarily unavailable
Retry the operation. If the error persists, collect the error details and request ID, if present, when you request help.
Docker authentication issues
The Docker authentication command is unavailable
Install or update the Databricks CLI (command-line interface) to the minimum supported version in Prerequisites, then run databricks auth docker configure again.
Docker cannot get registry credentials
Create or refresh a workspace OAuth profile, configure Docker for the registry region, and retry the Docker operation. Run the following commands:
databricks auth login --profile <profile>
databricks auth docker configure --profile <profile> --region <region>
Verify that <profile> points to the intended workspace. If you use the default profile, omit --profile <profile> from the Docker authentication command.
The Docker credential helper does not support profiles that use personal access tokens, OAuth machine-to-machine (M2M) credentials, or account-only authentication. For the complete authentication steps, see Set up Docker authentication.
A long-running push returns an authorization error
The Docker credential helper supplies a short-lived workspace OAuth access token. If a long-running push returns an authorization error, retry docker push so that the credential helper requests a new token. For the credential lifetime, see Limitations.
The registry hostname or region does not match
Verify that the registry hostname corresponds to the same cloud and region that you passed to databricks auth docker configure. Also verify that the selected Databricks CLI profile points to the intended workspace. Retag the image with the correct registry hostname before you retry a push.
Image push issues
The push returns a permission error
Verify that the principal has the privileges required for the push operation. See Grant permissions.
The image name is rejected
Use the <registry-hostname>/<catalog>.<schema>.<artifact>:<tag> format. For the artifact segment requirements, see Artifact name requirements.
The catalog or schema does not exist
Artifact Registry does not create catalogs or schemas. The target catalog and schema must already exist in Unity Catalog and be accessible from the workspace. Create the missing object or use an existing catalog and schema, then verify the required privileges before you retry the push.
Image discovery issues
The image or version does not appear
Confirm that the Docker push completed successfully and that you are listing the same catalog, schema, and artifact name that you pushed. Use the Software Artifacts API rather than the registry endpoint to list artifacts and versions. See Discover images and versions.
A registry operation is not supported
The registry endpoint does not support this operation. Use the Software Artifacts API to discover images and versions. For the restrictions, see Limitations.
Image acceleration issues
Image acceleration remains UNSPECIFIED
UNSPECIFIED does not identify a failure. See Limitations for image acceleration eligibility, including the image size limit. Larger eligible images take longer to convert. Check the status again later. If an eligible image does not reach SUCCESS after multiple hours, contact Databricks Support. For status definitions, see Check image acceleration status.
Get help
When you request help, include the following information:
- The cloud, region, workspace URL, and Databricks CLI version.
- The command that failed and its complete error message.
- The registry hostname and the
catalog.schema.artifact:tagname. - The image digest, API request ID, and operation timestamp, if available.
Share this information only through a private support channel. Do not post workspace URLs, registry hostnames, artifact names, or complete errors in public forums.
Remove tokens, passwords, and registry credentials from error messages, command output, and other diagnostics before you share them.