Uploaded image for project: 'Dev - Nexus Repo'
  1. Dev - Nexus Repo
  2. NEXUS-25275

improve docker repository human readable error response messages


    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: 3.27.0
    • Fix Version/s: 3.30.0
    • Component/s: Docker
    • Labels:
    • Notability:


      Docker API calls into Docker format NXRM repositories may returned errors. NXRM does not always include a useful human readable message or suitable error code.

      One Example Case Where Code and Message may be improved

      Configure the new Docker group repository docker-group with two members

      1. docker-hosted hosted repo with Deployment policy read only
      2. docker-proxy repo pointing at the official registry

      Make the Writable Repository of the group the docker-hosted repo.

      Add Docker Bearer Token Realm to Active realms.

      Using a docker client:

      docker login to the group repository

      docker login

      docker pull the latest hello-world image from the official docker registry and tag it for upload to group repo:

      docker pull hello-world:latest
      docker tag hello-world

      Try to push to the docker-group - this fails as expected, but with a very poor error message that will cause confusion to the end user.

      > docker push
      The push refers to repository []
      9c27e219663c: Layer already exists 
      blob upload invalid: blob upload invalid

      The error message is displayed this way because of how NXRM responded to the manifest PUT request:

      {"errors":[{"code":"BLOB_UPLOAD_INVALID","message":"blob upload invalid","detail":"Repository is read only: docker-hosted"}]}

      A slight tweak to the response payload to look like this instead:

      {"errors":[{"code":"UNSUPPORTED","message":"Group repository member docker-hosted is read only","detail":"Group repository member docker-hosted is read only"}]}

      Gives a much better user experience:

      docker push
      The push refers to repository []
      9c27e219663c: Layer already exists 
      unsupported: Group repository member docker-hosted is read only

      From https://docs.docker.com/registry/spec/api/#errors :

      The code field will be a unique identifier, all caps with underscores by convention. The message field will be a human readable string. The optional detail field may contain arbitrary json data providing information the client can use to resolve the issue.

      Supported error codes are documented here:



      Respond to docker errors with a more useful message suitable for end user consumption. This will help avoid support tickets and create a better user experience.




            mshevelov Mykyta Shevelov
            plynch Peter Lynch
            Last Updated By:
            Peter Lynch Peter Lynch
            NXRM - Trinity
            2 Vote for this issue
            6 Start watching this issue


              Date of First Response: