Have you seen this error on Wercker:

You have reached your pull rate limit. You may increase the limit by authenticating and upgrading: https://www.docker.com/increase-rate-limit"

Why is this happening?

On August 24th Docker announced new pull rate limits to Docker subscription plans:

  • Free plan – anonymous users: 100 pulls per 6 hours
  • Free plan – authenticated users: 200 pulls per 6 hours
  • Pro plan – unlimited
  • Team plan – unlimited

Okay, but I’m using Wercker not Docker Hub?

True, but the wercker.yml file contains the definition of your automation pipelines. The cornerstone of these configurations is the box statement. This statement names the Docker image that will run your pipelines. The following example refers to the Python 3.8.6 image.

box: python:3.8.6

If this is the style box statement you are using in your wecker.yml file, then a free plan anonymous user is being used to pull the image from Docker Hub. This pipeline, along with all the other Wercker pipelines using anonymous box statements, and all the other Docker users who are pulling anonymously eat into that 100 pulls per 6 hours pretty fast.

Create an Authenticated User

The first thing to do to resolve the pull rate error is to create a Docker Hub account. Once you have your account created, open the Security section in Settings.

Screenshot of the DockerHub security settings for a user. There is a section for access token to the right, and a button to create a new access token.

DockerHub security settings

Next, click the “New Access Token” button. A form appears where you type in a descriptive name for the token. This will help you remember what they are used for at a later date, which will make it easier for you to revoke tokens.

Dialog with a text field where a descriptive name for the access token can be entered.

New Access Token dialog

After pressing the “Create” button, another modal is displayed and it contains the access token.

Dialog with the access token displayed, and a button to copy the token to the clipboard and to close the modal.

Copy Access Token dialog

Clicking the “Copy and Close” button does what it says on the tin. The access token is copied to the clipboard, and the dialog is closed. The Access Tokens section now lists our newly minted token.

A table of access tokens, with a row showing the one we created in the last step.

Copy Access Token dialog

Using the Access Token

We now head back to our wercker.yml file and update the box statement. The image identifier is now referenced by the id statement, and the username and password contain the Docker Hub username, and newly created access token.

box:
  id: "python:3.8.6"
  username: joebloggs
  password: 09059282-ca28-20b0-b0de-4f4fc18d98f7

And that’s it, your Docker pulls from Wercker will no longer be affected by other anonymous users.

But… that hard-coded token is … bad

Yes, yes it is. A clean way to fix this issue is to store your Docker Hub username and access token as repository variables. In this example, the variables are named DOCKERHUB_USERNAME and DOCKERHUB_ACCESS_TOKEN.

A table of environment variables, showing two protected variables DOCKERHUB_USERNAME and DOCKERHUB_ACCESS_TOKEN

Wercker Environment Tab

Update wercker.yml again, this time replacing the hard-coded username and access token with the environment variables:

box:
  id: "python:3.8.6"
  username: $DOCKERHUB_USERNAME
  password: $DOCKERHUB_ACCESS_TOKEN

And that’s it. Hopefully your pull rate limit errors are now a thing of the past.