Troubleshooting Errors with Docker Commands When Using Amazon ECR
In some cases, running a Docker command against Amazon ECR may result in an error message. Some common error messages and potential solutions are explained below.
Error: "Filesystem Verification Failed" or "404: Image Not Found" When Pulling an Image From an Amazon ECR Repository
You may receive the error
Filesystem verification failed when
using the docker pull command to pull an image from an Amazon ECR
repository with Docker 1.9 or above, or the error
404: Image not
found when using Docker versions prior to 1.9.
Some possible reasons and their explanations are given below.
- The local disk is full
If the local disk on which you're running the docker pull command is full, then the SHA-1 hash that is calculated on the locally downloaded file may be different than the SHA-1 hash calculated by Amazon ECR. Check that your local disk has enough remaining free space to store the Docker image you are pulling. You can also delete old images to make room for new ones. Use the docker images command to see a list of all locally downloaded Docker images, along with their sizes.
- Client cannot connect to the remote repository due to network error
Calls to an Amazon ECR repository require a functioning connection to the Internet. Verify your network settings, and verify that other tools and applications can access resources on the Internet. If you are running the docker pull command on an Amazon EC2 instance in a private subnet, verify that your private subnet has a route to the Internet through a network address translation (NAT) server or through a managed NAT gateway.
Currently, calls to an Amazon ECR repository also require network access through your corporate firewall to Amazon Simple Storage Service (Amazon S3). If your organization uses firewall software or a NAT device that white lists allowed service endpoints, ensure that the Amazon S3 service endpoints for your current region are included in the whitelist.
If you are using Docker behind an HTTP proxy, you can configure Docker with the appropriate proxy settings. For more information, see HTTP proxy in the Docker documentation.
Error: "Filesystem Layer Verification Failed" When Pulling Images from Amazon ECR
You may receive the error
image image-name not found when
pulling images using the docker pull command. If you inspect the
Docker logs, you may see an error like the following:
filesystem layer verification failed for digest sha256:2b96f...
This error indicates that one or more of the layers for your image has failed to download. Some possible reasons and their explanations are given below.
- You are using an older version of Docker
This error can occur in a small percentage of cases when using a Docker version less than 1.10. Upgrade your Docker client to 1.10 or greater.
- Your client has encountered a network or disk error
A full disk or a network issue may prevent one or more layers from downloading, as discussed earlier about the
Filesystem verification failedmessage,. Follow the recommendations above to ensure that your filesystem is not full, and that you have enabled access to Amazon S3 from within your network.
HTTP 403 Errors or "no basic auth credentials" Error When Pushing to Repository
There are times when you may receive an HTTP 403 (Forbidden) error, or the error
no basic auth credentials from the docker
push command, even if you have successfully authenticated to Docker
using the aws ecr get-login command. The following are some known
causes of this issue:
- You have authenticated to a different region
Authentication requests are tied to specific regions, and cannot be used across regions. For example, if you obtain an authorization token from US West (Oregon), you cannot use it to authenticate against your repositories in US East (N. Virginia). To resolve the issue, ensure that you are using the same region for both authentication and docker push command calls.
- Your token has expired
The default token expiration period for tokens obtained using the
GetAuthorizationTokenoperation is 12 hours. However, if you use a temporary security credential mechanism such as multi-factor authentication (MFA) or AWS Security Token Service to authenticate and receive your token, the expiration period of the Amazon ECR authorization token is equal to the duration of these temporary security credentials. For example, if you call the aws ecr get-login command by assuming a role, the authorization token expires within 15 minutes to 1 hour, depending on the settings you use when calling the aws sts assume-role command.
- Bug in
Some versions of Docker for Windows use a credential manager called
wincred, which does not properly handle the Docker login command produced by aws ecr get-login (for more information, see https://github.com/docker/docker/issues/22910). You can run the Docker login command that is output, but when you try to push or pull images, those commands will fail. You can work around this bug by removing the
https://scheme from the registry argument in the Docker login command that is output from aws ecr get-login. An example Docker login command without the HTTPS scheme is shown below.Copy
docker login -u AWS -p