ARTIFACTORY: How to debug docker configuration issues

Scott Mosher
2022-06-23 09:15

Docker debugging and understanding what to expect from the incoming requests

In this article, we will not go over the Docker configuration steps outlined already in our wiki at, but will help understand what the configuration achieves, how it works with Artifactory and how to debug if we run into issues with the configuration.

Each Docker method (Repository Path, sub-domain, and Port) is used to format requests in a way Artifactory expects.  It does not ultimately change how Artifactory handles incoming Docker requests.  We will go through the expected requests that we can parse for each request type.

Docker login:

We will always see 401s with the Docker client during the initial authentication request and this is expected.  The Docker client sends credentials once the 401 is returned.  
|user|GET|/api/docker/null/v2/token|200|  (the null in this request can also be the repository name we are logging into, but in this request, we are getting a token for the Artifactory registry itself)

We can further debug to gather a bit more information by mimicking the Docker login via curl (this is repository path specific request, but can be updated for other methods) e.g.

curl -uuser http://PLATFORM_URL/v2/DOCKER_REPO/token -v


Pulling Docker images:

For Docker pulls, we don’t expect the same 401s.  We now have the token, so we should see the user authenticated within the request.  We now expect HEAD and GET requests.

We then start to see the manifest pull.

Once we get the manifest/s, we can then pull the actual blobs.

Again, we can further test out this pull with a curl request.  We will be using the token returned from the previous login request we ran.

curl -H "Authorization: Bearer <TOKEN>" -vk

(in this example docker is a virtual repository that contains a Docker remote repository pointing to dockerhub)

Pushing Docker images

For Docker pushes, these requests are not as straightforward.  Again, all these requests should be authenticated and will initially be HEAD requests.

We then see the POST command uploading to the temporary uploads directory.

The then should see following PATCH and PUT requests for the blobs and the last request would be the manifest/tag.


Understanding proxy configuration and how to debug

We will take a generic nginx reverse proxy configuration as this or Apache would be used when setting up the sub-domain Docker method.  The necessary configuration that is required is to set the servername and rewrite.

server_name ~(?<repo>.+).PLATFORM_URL PLATFORM_URL;
rewrite ^/(v1|v2)/(.*) /artifactory/api/docker/$repo/$1/$2; 

This takes the repository provided in the subdomain to construct the request as Artifactory expects.  We can also look to the headers we set if we continue to see issues.

proxy_set_header    X-Forwarded-Port  $server_port;
proxy_set_header    X-Forwarded-Proto $http_x_forwarded_proto;
proxy_set_header    Host              $http_host;

The POST commands above will take the header set within the request and push the PATCH requests to this location.  If we see the POST commands hit Artifactory as expected, but the PATCH requests are failing, this usually is a result of an invalid header.

Putting this all together

Taking the above expected requests along with understanding the purpose of the reverse proxy configuration allows for us to further debug and pinpoint possible places where the issue originates.  Even without a reverse proxy, we still can further troubleshoot by just understanding what we expect in the logs.  

The first thing to confirm is the request structure.  We expect to see within the artifactory-request.log, that each request starts with the /api/docker/REPO_NAME.  If we don’t see this format, we can then point to the Docker request or reverse proxy configuration as the cause of the issue as Artifactory is receiving an incorrectly formed request.

A couple examples of bad requests and what cause them:


(the repository name is missing which could be caused by the reverse proxy not having the $repo variable set properly)


(caused by the v2 request from the Docker client not being rewritten to /api/docker/REPO_NAME/…)


(Docker pull request does not have the repository name within the request)

Another couple of common causes for Docker issues within the Artifactory configuration would be the Docker method we are using does not match the selected Docker method under the Artifactory -> Http Settings tab on the Admin panel.  We also need to confirm the Default Deployment Repository is set within the virtual repository we are hitting.