How to troubleshoot Docker problems

Patrick Russell
2018-11-13 23:41


Comparing correct Docker REST API calls can show where the problem lies.

Affected Versions

4.0.2 – Latest


When troubleshooting Docker errors it is best to compare what is supposed to happen against what is currently happening. You can eliminate a great deal of noise by simulating each step the client takes, and examining what HTTP return code is sent by Artifactory.

In general, these return codes indicate where to look next:
403 and 401 – Authentication issue, examine authorization settings
404 – Resource not found, check repository for resource
400 – Incorrect request, use curl to get reason phrase
50X – Server problem, examine artifactory.log


Using curl
The libcurl terminal application can make basic REST API commands such as GET or PUT options. The Artifactory request logs display the exact API commands the Docker client uses.

You can use the examples below, or substitute the one that is failing in the Artifactory request.log file. Doing so should yield further information on the problem, and possible next steps.

Basic usage (with #comments):

curl -uadmin #Artifactory-username -vvv #verbosy -k #ignore-insecure-SSL -XGET #GET-request http://localhost:8081/artifactory/api/system/ping

Curl uses GET requests by default. Other commands like "PUT" require the –data field, along with the (Usually JSON) data payload. An example PUT command:

curl -uadmin:password -XPUT -H"Content-type: Application/json" –data '{"name":"test-group"}' http://localhost:8081/artifactory/api/security/groups/test-group

docker login
These are the backend steps that occur when a user tries to authenticate against Artifactory:
docker login

"docker" is the name of the virtual repository
*.art.local is the web address used by a reverse proxy configured for Subdomain Docker repositories

1. The Docker client checks the existence of Artifactory via an Anonymous GET request:


The 401 HTTP code is expected if Artifactory does not allow Anonymous access to the repository in question. If a 200 is seen by the Docker client credentials are not used.

2. The Docker client gets an access token:


This can be replicated via the following curl command:

curl -u<USERNAME> http://art.local:8081/artifactory/api/docker/docker/v2/token

Which returns a JSON with the token value:

docker pull
When a user attempts to pull an image, several steps should occur in sequence:
docker pull
1. Docker checks for the manifest.json of the file:
2. The client uses the information in the manifest file to pull the image layers that make up the image:
This completes the pull. If a layer is missing, the container's manifest should be inspected, and all layer requests should return a 200 OK.

docker push
When a user is ready to push an image, several checks occur before the file is uploaded:
docker push

1. The Docker client will check for the existence of the layers it needs to push:

A 404 not found is expected at this stage if the layer does not exist on Artifactory yet.

2. The client runs a POST command to submit the blob metadata:

3. The client will PATCH the rest of the blob metadata to Artifactory:
4. Finally the client sends the layer binary:
5. Artifactory moves the binaries from a temporary _uploads folder to the Docker image's main location at the base directory of the repository: