This topic describes how to troubleshoot common faults on the Docker client.

Failure to run the docker login command

If you fail to log on to a registry by running the docker login command, perform the following steps to troubleshoot the fault:

  • Make sure that the password you use is the independent one for logon to the registry, instead of the logon password for your Alibaba Cloud account. You can set and change the password for logon to the registry in the Container Registry console by performing the following steps:
    1. Log on to the Container Registry console.
    2. On the instances page, click an instance to go to the instance details page.
    3. In the left-side navigation pane, choose Repositories > Access Credential.
    4. On the Access Credential page, click Set Password in the upper-right corner.
    5. In the Set Password dialog box, set a password for logon to the registry and click Confirm.
  • Check whether you use the sudo docker login command. If yes, the first password you enter must be the Linux user password. If you enter the password for logon to the registry here, the logon fails.

    If you enter the wrong Linux user password as the first password, the Docker client prompts you to try again and allows you to make up to three attempts. However, the Docker client exits immediately after you enter the password for logon to the registry as the first password. In this case, the following error is returned:

    Error response from daemon: Get https://registry.cn-hangzhou.aliyuncs.com/v2/: unauthorized: authentication required                    

Failure to run the docker pull command

The following error is returned after you run the docker pull command: Error: image xxx not found.

The preceding error indicates that you fail to pull an image. To troubleshoot the fault, perform the following steps:

  • If you attempt to pull an image from a public repository, check whether the image URL is correct.

    Log on to the Container Registry console and search the public repository for the image tag you want to pull. Make sure that the image tag exists.

  • If you attempt to pull an image from a private repository, check whether your account has logged on to the registry from which you want to pull the image.
    1. Run the following command to display the domain names of all the registries your account has logged on to:
      cat ~/.docker/config.json                    
    2. Check whether the domain name of the registry from which you want to pull the image exists in the command output.

      If no, log on to the registry.

      If yes, check whether your logon account has the permission to pull the image. A RAM user has no permission by default. For more information about repository access control, see Repository access control.

    Note In rare cases, the following error is returned, indicating that the pulled block files fail the verification. If this error occurs, try again.

    Error: filesystem layer verification failed for digest

Failure to run the docker push command

The following error is returned after you run the docker push command: denied: requested access to the resource is denied.

The preceding error indicates that you fail to push an image. The troubleshooting procedure is similar to that for troubleshooting a failure to run the docker pull command. The only difference is that higher permissions are required for the logon account.