# Cloudflare connection troubleshooting

Source: [Cloudflare connection troubleshooting](https://typeroll.com/docs/guides/cloudflare-troubleshooting/)

> Every reason Connect Cloudflare can stop, who can fix it and how, for the Publishing page, Hosting Groups, the API and MCP.

When **Connect Cloudflare** does not finish, the **Cloudflare account** card on the **Publishing** page explains why, inside the card. Each Hosting Group card does the same for its own hosting account. The card shows the Cloudflare accounts you authorized, whether each can be used, and for each reason who can fix it and one button for the fix. This page lists every reason by its code. The same codes are returned by the [API and MCP](https://typeroll.com/docs/guides/cloudflare-troubleshooting/#api-and-mcp).

This applies to Typeroll Cloud and self-hosted installations with customer publishing enabled. In Typeroll Cloud, the *publisher* is Typeroll. On a self-hosted installation, the publisher is the operator who configured its Cloudflare OAuth client. See [Publishing with your own accounts](https://typeroll.com/docs/guides/customer-publishing/) for the normal setup.

## The steps in the card

1. **Publisher ready**: the publisher has configured Cloudflare sign-in.
2. **Sign in to Cloudflare**: you approve Typeroll’s access on Cloudflare’s consent page and select the accounts it may use.
3. **Choose account**: if you authorized one account, it is used. If you authorized several, you choose one in the card.
4. **Access verified**: Typeroll checks Cloudflare Pages access in the account, because it creates each site’s Pages project there.
5. **Connected**: the account is saved for this Organization or Hosting Group.

Typeroll keeps the latest result for 24 hours, so a reload shows the same explanation. Only you see the result of your own sign-in and the accounts you authorized; other owners and admins see the connection once it is saved.

## Who can fix it

Each reason starts with a **Who acts** label, followed by the reason itself.

| Who acts                         | Who that is                                                                              |
| -------------------------------- | ---------------------------------------------------------------------------------------- |
| You                              | The Typeroll organization owner or admin connecting Cloudflare                           |
| Cloudflare account administrator | A Super Administrator of the Cloudflare account, who can change members’ roles           |
| Typeroll publisher               | The operator of this Typeroll installation (Typeroll in Cloud)                           |
| Typeroll administrator           | Whoever manages the other Typeroll Organization that already uses the Cloudflare account |

## Choosing between several accounts

If you select more than one account on Cloudflare’s consent page, the card lists them with their status and asks you to choose. Typeroll does not choose for you, even when only one of them has Pages access: the account you connect hosts this Organization’s sites, is reserved for this Organization, and a later reconnect must use the same account. An account that cannot be used shows its reason and cannot be selected.

The choice stays open for 10 minutes, and the card shows until when. After that it says the choice expired. Within an hour of signing in, **Check again** lists and checks the same accounts again and opens a new 10-minute choice, without another sign-in. Later, select **Connect Cloudflare again**. Check again never connects an account by itself.

## Sign-in

### `oauth_cancelled`

**You.** You selected **Cancel** on Cloudflare’s consent page, so nothing changed. Select **Connect Cloudflare again** and choose **Authorize**.

### `state_expired`

**You.** The sign-in was older than 10 minutes, was already used, or was started in another tab or Typeroll Organization. A sign-in that never returned from Cloudflare, for example because its page was closed or showed an error, is also reported this way after 10 minutes. Start again from the card and finish in the same browser. A return that does not match a sign-in started in your browser changes nothing.

### `wrong_browser`

**You.** Cloudflare returned to a different browser, browser profile or address than the one that started sign-in. Start again in one browser, using the portal’s usual address.

### `session_expired`

**You.** Your Typeroll session ended while you were on Cloudflare. Typeroll asks you to sign in and then returns you to the Cloudflare card. Select **Connect Cloudflare again**.

## Permissions and accounts

### `permissions_missing`

**You.** Cloudflare granted fewer permissions than Typeroll needs. The reason names the missing ones (`missing_permissions` in the API), for example **Cloudflare Pages: Edit** or **Workers R2 Storage: Edit**. Connect again and approve every requested permission. If Cloudflare does not offer them, your role in the account does not include them: ask a Super Administrator of the account to connect it, or to give you a role that does. Domain and DNS permissions are optional and never cause this reason. On a saved connection, **Check again** reports this when the saved authorization lacks a permission.

### `no_eligible_account`

**You.** Cloudflare did not give Typeroll access to any account. Connect again and select the account that should host your sites on the consent page.

### `too_many_accounts`

**You.** More than 1,000 accounts were authorized. Connect again and select only the account you want to use.

### `account_choice_expired`

**You.** You authorized several accounts and did not choose one within 10 minutes. See [Choosing between several accounts](https://typeroll.com/docs/guides/cloudflare-troubleshooting/#choosing-between-several-accounts).

### `locked_to_account`

**You.** This Organization or Hosting Group already uses another Cloudflare account, and sites and media depend on it. Cloudflare authorized a different account, so nothing changed. Connect again and select the account the card names. Moving to another account needs a hosting migration; for another account in addition, create a Hosting Group.

### `pages_access_denied`

**Cloudflare account administrator.** Cloudflare refused access to Cloudflare Pages in the account. Typeroll creates each site’s Pages project there, so your role in the account must include Cloudflare Pages, for example **Administrator** or **Cloudflare Pages Admin**. The card links to the account’s members page, where a Super Administrator changes your role. Then select **Check again** within an hour of signing in, or connect again. Projects that Wrangler deployed as Workers with static assets do not matter: Typeroll only needs Pages access.

### `claimed_by_other_organization`

**Owner or admin of the Organization that uses the account.** Another Typeroll Organization already uses this Cloudflare account. Several Organizations may share one account, for example one owner with several companies, or companies kept in separate Organizations so that a site can be transferred later. To prove common control, only a person who is an owner or admin of at least one Organization that already uses the account can connect it to another Organization. Typeroll checks both roles when the account is connected.

The reason never names the other Organization, because you may not be a member of it. To continue:

* If you administer that Organization too, sign in to Typeroll as yourself and connect the account again from this Organization. The card then names the Organizations you administer and asks you to confirm sharing the account.
* Otherwise ask an owner or admin of that Organization to connect the account here (they need owner or admin access to this Organization as well), or ask Typeroll support.

An organization API key acts for no person, so it cannot join an account that another Organization uses: connect it in **Publishing** in a browser. An Organization whose own saved connection already uses the account can always reconnect it.

#### Sharing one Cloudflare account

When you connect an account that Organizations you administer already use, the card says **This Cloudflare account is also used by: …** and asks you to confirm. Sites stay separate:

* Every Pages project, Worker and media bucket Typeroll creates gets a name derived from its own Organization (and Site), and Typeroll records which Organization owns it. An operation on a resource that belongs to another Organization stops with `cloudflare_resource_owned_by_other_organization`; nothing is changed.
* Each Organization keeps its own private and public R2 buckets and media hostname. Two Organizations never share a bucket.
* A hostname that serves another Organization’s site in the same account is never prepared for replacement (`hostname_used_by_other_organization`).
* The shared build engine never uses the account’s only build token by assumption when other Organizations use the account: select the token on this Organization’s build project in Cloudflare.
* Disconnecting removes only this Organization (or Hosting Group). The other Organizations stay connected; the account is free for anyone once no Organization uses it.

Cloudflare’s own limits apply to the whole account, not to each Organization: for example the number of Pages projects, R2 buckets, Workers, custom domains and builds that can run at once. Zones and DNS records are visible to everyone with access to the account.

### `authorization_revoked`

**You.** Cloudflare no longer accepts Typeroll’s authorization for a saved connection. It may have been revoked in Cloudflare, or not used for a long time. Select **Reconnect Cloudflare** and approve the same account; sites, media and settings are kept.

## Temporary problems

### `provider_unavailable`

**You.** Cloudflare did not respond as expected. Nothing was changed. When the failure happened after you approved access, **Check again** continues within the hour without a new sign-in; otherwise connect again.

### `rate_limited`

**You.** Cloudflare is limiting requests. The reason says how long to wait (`retry_after` in seconds in the API).

### `revision_conflict`

**You.** The connection changed in another tab or session while you were connecting, for example a disconnect. Nothing was overwritten. Review the current state and try again.

## Publisher setup

### `publisher_oauth_misconfigured`

**Typeroll publisher.** The publisher’s Cloudflare sign-in is missing or Cloudflare rejected its settings. Nothing in your Cloudflare account needs to change. In Typeroll Cloud, contact Typeroll support. The operator checks the OAuth client in Cloudflare:

* **Redirect URI**: `{PORTAL_PUBLIC_URL}/api/orgs/publishing/cloudflare/callback`
* **Grant types**: authorization code and refresh token. Without the refresh token grant Cloudflare issues no refresh token and the reason says so.
* **Token endpoint authentication**: `client_secret_basic` is preferred; Typeroll retries once with `client_secret_post` when Cloudflare rejects HTTP Basic for the client.
* **Scopes**: every scope Typeroll requests must be allowed for the client, otherwise Cloudflare answers `invalid_scope` before the consent page. This includes each optional scope listed in `TYPEROLL_PUBLISH_CLOUDFLARE_OPTIONAL_SCOPES`; see [Self-hosting](https://typeroll.com/docs/guides/self-hosting/#cloudflare-sign-in-for-customer-publishing).
* The client ID, secret and encrypted credential storage (`TYPEROLL_PUBLISH_CLOUDFLARE_CLIENT_ID`, `TYPEROLL_PUBLISH_CLOUDFLARE_CLIENT_SECRET`, `INTEGRATIONS_SECRET_KEY`) and an HTTPS `PORTAL_PUBLIC_URL`.

## API and MCP

An organization API key can read the same explanation for each Hosting Group:

| Action                            | MCP tool                                                              | API route below `/api/v1`                                 |
| --------------------------------- | --------------------------------------------------------------------- | --------------------------------------------------------- |
| Explain the Cloudflare connection | `diagnose_organization_cloudflare_connection`                         | `GET /publishing/cloudflare-diagnosis`                    |
| Explain a Hosting Group           | `diagnose_organization_cloudflare_connection` with `hosting_group_id` | `GET /publishing/cloudflare-diagnosis?hosting_group={id}` |
| Re-check a saved connection       | `diagnose_organization_cloudflare_connection` with `recheck: true`    | `GET /publishing/cloudflare-diagnosis?recheck=true`       |

The response contains `outcome` (`connected`, `needs_attention`, `choose`, `action_required`, `sign_in_pending`, `sign_in_required`, `retryable_error` or `unavailable`), `blockers`, `primary_action` and, for a saved connection, its account with `usable` and `blockers`, plus `connect_url`. It is the Organization’s state: a person’s unfinished sign-in and the accounts they authorized stay in their own card; a reason about such an account keeps its code and fix without naming the account. Each blocker has `code`, `who` (`you`, `cloudflare_account_admin`, `organization_admin`, `publisher` or `typeroll_admin`), `message` and one `action`. Link actions point to `https://dash.cloudflare.com/` or this documentation. Sign-in and **Check again** of an unfinished connection happen in a browser at `connect_url`; an API key cannot act as a person on Cloudflare. `recheck=true` re-verifies a saved connection with its own authorization: renewal, account access, Cloudflare Pages access and granted permissions. No tokens or Cloudflare responses are returned.