TL;DR#

When working with cloudflare/wrangler-action, you should either:

• Enable User > User Details > Read Permissions and User > Memberships > Read Permissions for the User API Token ¹

• Or explicitly set the accountId field

The Starting Point#

The cloudflare/wrangler-action confused me so many times when every time I tried to deploy my project to cloudflare worker / pages (Though, it’s still an amazing platform). The confusion mainly comes from the documentation of cloudflare/wrangler-action:

• It doesn’t mention whether the accountId field is required or not.
• The example sometimes uses accountId and sometimes doesn’t.
• The error message sometimes requires me to enable unrelated permissions.

Debug the Action#

From the minimal config#

I try to deploy my worker with the minimal config:

- uses: actions/checkout@v4
- name: Deploy
uses: cloudflare/wrangler-action@v3
with:
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

While this apiToken only has the Account > Cloudflare Pages > Edit permission, however, I got the error message:

You are logged in with an API Token. Unable to retrieve email for this user. Are you missing the `User->User Details->Read` permission

Sure, it make sense that cloudflare need the account information, and I will give you the User > User Details > Read permission. But I still got the error message:

A request to the Cloudflare API (/memberships) failed.

This is a wired error message, I still don’t know why it required memberships permission. ² However, everything works fine after I enable the User > Memberships > Read permission.

The experiment#

To figure out the problem, I tested the action with different combinations of permissions and accountId field:

As you can see, if you don’t want to specify the accountId field, you need to enable both User > User Details > Read Permissions and User > Memberships > Read Permissions. This also get confirm by the cloudflare API tokens templates. It says edit cloudflare workers require User Details Read and User Memberships Read permissions. Unfortunately, the documentation of cloudflare/wrangler-action doesn’t mention this.

Outro#

Cloudflare has a lot of amazing products, but the token permission system is somehow confusing for the users. Especially the documentation doesn’t mention what Exactly an API token is (user or account token?) and what permissions are required for each product. I hope this article can help you to debug the wrangler action and make your life easier.