title: How to push an image to a docker registry using the docker Registry API v2
body: <p>I'm a writing a docker registry API wrapper to pull images from one private registry and push them to another. </p>
  
  <p>Based on the <a href="https://docs.docker.com/registry/spec/api/" rel="nofollow noreferrer">documentation</a> first I need to pull the manifest and the layers for an <code>image:tag</code>. Following  <a href="https://docs.docker.com/registry/spec/api/#pulling-an-image" rel="nofollow noreferrer">Puling An Image</a> I've successfully downloaded all the layers for a particular <code>image:tag</code> and the manifest.  </p>
  
  <p>Following <a href="https://docs.docker.com/registry/spec/api/#pushing-an-image" rel="nofollow noreferrer">Pushing An Image</a> I've followed the steps:</p>
  
  <ol>
  <li><code>POST /v2/&lt;name&gt;/blobs/uploads/</code> (to get the UUID i.e. <code>Location</code> header)</li>
  <li><code>HEAD /v2/&lt;name&gt;/blobs/&lt;digest&gt;</code> (check to see if it already exists in the registry)</li>
  <li><code>PUT /v2/&lt;name&gt;/blobs/uploads/&lt;uuid&gt;?digest=&lt;digest&gt;</code> (<code>Monolithic Upload</code> )</li>
  </ol>
  
  <p>What's not clear to me are the following:</p>
  
  <ol>
  <li>Is the <code>UUID</code> unique to each individual layer I push or is that reused for all layers (e.g. Do I need to run a new POST for each layer an get a new <code>UUID</code> before I attempt to upload it?).</li>
  <li>The <a href="https://docs.docker.com/registry/spec/api/#completed-upload" rel="nofollow noreferrer">Completed Upload</a> section indicates </li>
  </ol>
  
  <blockquote>
    <p>For an upload to be considered complete, the client must submit a PUT
    request on the upload endpoint with a digest parameter</p>
  </blockquote>
  
  <p>However, as mentioned I'm using the <a href="https://docs.docker.com/registry/spec/api/#monolithic-upload" rel="nofollow noreferrer">Monolithic Upload</a> which uses a <code>PUT</code> and would be the same request as what shows in the Completed Upload section.  So by doing a monolithic upload am I also completing the upload at the same time?</p>
  
  <p><strong>Problem</strong></p>
  
  <ol>
  <li><p>When I go through all the steps above I receive the <code>BLOB_UNKNOWN</code>  error when uploading a digest, e.g.</p>
  
  <p>{
      "errors:" [{
              "code": "BLOB_UNKNOWN",
              "message": "blob unknown to registry",
              "detail": {
                  "digest": 
              }
          },
          ...
      ]
  }</p></li>
  </ol>
  
  <p>According to the docs this error is produced when pushing a manifest and one of the layers in the manifest are unknown:</p>
  
  <blockquote>
    <p>If one or more layers are unknown to the registry, BLOB_UNKNOWN errors
    are returned. The detail field of the error response will have a
    digest field identifying the missing blob. An error is returned for
    each unknown blob. The response format is as follows:</p>
  </blockquote>
  
  <p>What confuses me about this is</p>
  
  <ol>
  <li>I'm pushing a digest (aka a layer) not the manifest so why is this error returning?</li>
  <li>I would expect the blob to be unknown because I'm pushing a new image into the registry</li>
  </ol>
  
  <p>For now I'm going to use the docker client, but I haven't found any wrapper examples on-line to see how this is pulled off.  Presumably I'm missing some logic or misunderstanding the docs, but I'm not sure where I'm going wrong?</p>