Troubleshoot Docker login, push, and pull errors

Troubleshoot docker login failures

Why does docker login fail?

If the login fails, check the following possible causes.

• The login may fail if you use your Alibaba Cloud account password instead of the dedicated password for Container Registry. To set or modify the password for the registry, follow these steps in the Container Registry console:

  1. Log on to the Container Registry console.

  2. On the Instances page, click an instance.

  3. In the left-side navigation pane, choose Instances > Access Credentials.

  4. On the Access Credentials page, click Set Password in the upper-right corner.

  5. In the Set Password dialog box, set the login password for the registry and click Confirm.

• Another cause is using sudo to log in. If you use sudo, the first password prompt is for your Linux user password. Entering the registry password at this prompt causes the login to fail.

  The Linux password prompt is different from the registry password prompt. The Linux prompt usually allows three attempts and displays a "try again" message. In contrast, an incorrect registry password causes the process to exit after one attempt and returns the following error:

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

• When using a RAM user, do not use your Alibaba Cloud account password. Instead, you must set and use a dedicated password for the RAM user in the Container Registry console. For more information, see Configure access credentials.

What should I do if docker login fails with a "Bad Request" error?

If the ECS node has an HTTPS_PROXY proxy configured, Docker daemon requests are routed through the proxy, which can cause unexpected errors and return a Bad Request error during docker login.

To resolve this issue:

1. Check whether proxy-related configuration files exist in the /etc/systemd/system/docker.service.d/ directory.

2. Back up and delete the proxy configuration files in that directory (for example, http-proxy.conf or https-proxy.conf).

3. Run systemctl daemon-reload && systemctl restart docker to reload the configuration and restart Docker.

4. After clearing the proxy configuration, run docker login again.

Why does docker login time out?

A network connectivity issue can prevent access to the instance and cause the docker login command to time out. For more information, see Network access control.

Troubleshoot docker pull failures

docker pull fails with an "image not found" error

The error message is similar to Error: image xxx not found.

If the pull operation fails, check the following possible causes.

• Check the image address:

  • Verify that the image address is correct, especially for public images.

  • Find the correct image address and tag in the Container Registry console.

• Check your login status for a private repository:

  • Run cat ~/.docker/config.json to view the domain names of logged-in registries. Ensure that your private repository's domain is listed.

  • If you are not logged in, run the docker login command to authenticate.

• Check your account permissions:

  • Confirm that your account has permission to pull the image. For example, a RAM user may not have the required permissions by default.

  • Manage permissions in the repository's access control settings. For more information, see Repository access control.

Why can't I anonymously pull an image from an Enterprise Edition instance?

To pull images anonymously, go to the Overview page and, in the Instance Settings section on the right, turn on Pull from Anonymous Users.

Why do pulls from an overseas registry mirror fail?

Pulls of specific image versions from overseas registry mirrors may fail due to carrier network instability or other factors. For more information, see Image Accelerator.

docker pull returns a "manifest unknown" error, but the image exists in the repository

This error is usually caused by a CPU architecture mismatch between the client and the image. For example, the client runs on an ARM architecture but the image only has an AMD64 manifest.

To troubleshoot:

1. Check the client's CPU architecture (ARM or AMD64) by running uname -m or docker info.

2. Try running docker pull on a server with the matching architecture to verify whether the pull succeeds.

3. If you cannot provide account access for reproduction, rebuild and push the image with a new tag. Incomplete manifest information for a specific tag can result from architecture configuration issues during the build process. Rebuilding and pushing the image with a new tag usually resolves the issue.

Troubleshoot docker push failures

docker push fails with the error "denied: requested access to the resource is denied"

When an image push fails, the main troubleshooting steps are similar to those for a docker pull failure. However, a docker push operation requires higher permissions.

Why does docker push fail?

Before you push an image, ensure a repository for it exists. If not, ensure that automatic repository creation is enabled for the namespace.

docker push fails due to security group or user permission issues

Container Registry does not have security group configurations, so push failures are generally not caused by the client's security group settings. If your push fails, try the following:

• Check the local environment configuration. Switch to the root user to run docker login and docker push.

• Avoid using sudo or running Docker as a non-root user (for example, on macOS or Kylin Linux). Different users have separate Docker credential storage paths (~/.docker/config.json), which can prevent credentials from being correctly updated and cause the push to fail.

docker push fails with "certificate has expired or is not yet valid"

To resolve this error:

1. Back up and delete the existing configuration from ~/.docker/config.json.

2. In the Container Registry console, obtain a new login command or set new access credentials.

3. Run docker login to authenticate again, then retry the push.

How does the Docker client handle an expired or missing token during docker push?

When you run docker push, if the current token has expired or does not exist, the Docker client automatically uses the username and password stored in ~/.docker/config.json (the Base64-decoded value of the auth field) to send a request to the dockerauth service and obtain a new token. No manual intervention is required.

What is the size limit for a single streaming layer push to Container Registry?

The recommended maximum size for a single streaming layer push to Container Registry is 100 GB. Each individual layer should not exceed this limit.