Troubleshoot federated agent access changedclaude-tag/admins/federated-access/troubleshooting
Nearest release: v2.1.286, published an hour before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 30 Sep 2026 19:12 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 30 Sep 2026 19:37 UTC.
Upstream edited
Recorded here
Lines+16added
Lines−16removed
From line
1
where the diff opens
First seen
10 Sep 2026
this site's first read of the page
Recorded edits9to this page, all time
# Troubleshoot federated agent access # Troubleshoot federated cloud access
The whole hunk
from line 1, old and new numbered
/
from line 1
1# Troubleshoot federated cloud access
1# Troubleshoot federated agent access
22
3> Errors from Claude Tag's federated cloud access and what fixes each: console dialog messages, requests Claude reports as blocked or failed, and rejections your gateway, AWS, Google Cloud, or authorization server records.
3> Errors from Claude Tag's federated agent access and what fixes each: console dialog messages, requests Claude reports as blocked or failed, and rejections your gateway, AWS, Google Cloud, or authorization server records.
44
55export const BetaNote = () => <Info>Claude Tag is in public beta. Features and behavior described here may change before general availability.</Info>;
66
77<BetaNote />
88
9<Note>Federated connections are managed at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated cloud access** in the left navigation. Changing them needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
9<Note>Federated connections are managed at [`claude.ai/admin-settings/claude-tag`](https://claude.ai/admin-settings/claude-tag): open **Federated agent access** in the left navigation. Changing them needs an organization Owner, or an admin with full Claude Tag management permission.</Note>
1010
11This page covers what goes wrong after you connect a gateway, AWS role, Google Cloud identity, or authorization server through **Federated cloud access**. It's organized by where the problem shows up: a message in a console dialog, an error Claude reports in the thread, or a rejection in your own logs. The token terms used below are explained on the [identity token reference](/docs/claude-tag/admins/federated-access/token-reference).
11This page covers what goes wrong after you connect a gateway, AWS role, Google Cloud identity, or authorization server through **Federated agent access**. It's organized by where the problem shows up: a message in a console dialog, an error Claude reports in the thread, or a rejection in your own logs. The token terms used below are explained on the [identity token reference](/docs/claude-tag/admins/federated-access/token-reference).
1212
1313First confirm two things that have nothing to do with federation:
1414
from line 24
2424| Message | What it means | Do this |
2525| :- | :- | :- |
2626| "The check can't run right now. Try again later, or skip the check and record why." | Anthropic couldn't produce the test tokens for the connection check. The problem is on Anthropic's side, not your gateway's. | Wait a few minutes and click **Run check and connect** again. If the message persists, select the **Skip the check** option, enter a **Reason for skipping**, and click **Connect without the check**; remove and reconnect the gateway later to record a passed check. |
27| "Too many checks in a short time." followed by how long to wait | Your organization ran the connection check too many times in quick succession. The limit counts every admin in the organization. Entering an address that is already registered runs the check again and counts too, unless the **Skip the check** option is selected. | Wait the time the message names. To add an existing gateway to a bundle, click **Add to bundle** in its row of the **Gateways** table instead of entering its address again. |
27| "Too many checks in a short time." followed by how long to wait | Your organization ran the connection check too many times in quick succession. The limit counts every admin in the organization. Entering an address that is already registered runs the check again and counts too, unless the **Skip the check** option is selected. | Wait the time the message names. To add an existing gateway to a bundle, click **Add to bundle** (**Add to another bundle** on a row already in one) in the **Gateways** table instead of entering its address again. |
2828| "Too many attempts in a short time." in the **Connect an authorization server** dialog | A general request limit, not the connection check; registering a token endpoint never runs the check. | Wait the time the message names and try again. |
2929| "Connecting a gateway needs full Claude Tag management permission. Ask an organization owner." or "This needs full Claude Tag management permission. Ask an organization owner." | Your account can't change federated connections. Channel managers, and admins whose Claude Tag permission covers specific channels only, can't connect a gateway, cloud role, or authorization server. | Ask an organization Owner, or an admin with full Claude Tag management permission, to make the connection from their own account. |
30| A dialog message containing "isn't enabled for your organization yet", or **Federated cloud access** is missing from the left navigation | Federated cloud access isn't available to organizations whose compliance configuration excludes it. The navigation item is also hidden from channel managers and from admins whose Claude Tag permission covers specific channels only, because connecting a system needs full Claude Tag management permission. | Ask an organization Owner, or an admin with full Claude Tag management permission, to open the page. If it's missing for them too, your organization's compliance configuration excludes the feature. |
30| A dialog message containing "isn't enabled for your organization yet", or **Federated agent access** is missing from the left navigation | Federated agent access isn't available to organizations whose compliance configuration excludes it. The navigation item is also hidden from channel managers and from admins whose Claude Tag permission covers specific channels only, because connecting a system needs full Claude Tag management permission. | Ask an organization Owner, or an admin with full Claude Tag management permission, to open the page. If it's missing for them too, your organization's compliance configuration excludes the feature. |
3131| "This organization has reached its limit of 5 gateways. Remove one to connect another." or, in the **Connect an authorization server** dialog, "…limit of 5 registered gateways, which includes token endpoints." | An organization can register 5 addresses. A token endpoint is registered the same way as a gateway, so it counts toward the same 5 and appears in the **Gateways** table marked "Used by a connected authorization server. Manage it from the Authorization servers section." An address is either a gateway or a token endpoint in your organization, not both. | In the **Gateways** table, click **Remove** in the row of a gateway you no longer use. To free a token endpoint's row, click **Remove** in the server's row of the **Authorization servers** table first, then remove the endpoint from the **Gateways** table. See [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). |
32| "This gateway is already registered. Close this dialog and pick it from the list to add it to a bundle." | The address is already registered in your organization, and the dialog couldn't load its row to continue. This message is rare: entering a registered address normally runs the connection check again without changing the stored result, then moves on to the bundle step. | Click **Cancel**, then click **Add to bundle** in the gateway's row of the **Gateways** table. |
33| "`<address>` is already in the bundle `<bundle>`. Assign that bundle to a channel to use the gateway there.", "This role is already connected in the bundle `<bundle>`.", or "This token endpoint is already connected in the bundle `<bundle>`." | A gateway, AWS role, or token endpoint can be connected in only one Access bundle, and this one already is. | To use the connection in more channels, [attach that bundle to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead. To move it, in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, and choose **Delete**. Then add it to the new bundle: **Add to bundle** in the gateway's row of the **Gateways** table, or the connect dialog again for the other types. |
32| "This gateway is already registered. Close this dialog and pick it from the list to add it to a bundle." | The address is already registered in your organization, and the dialog couldn't load its row to continue. This message is rare: entering a registered address normally runs the connection check again without changing the stored result, then moves on to the bundle step. | Click **Cancel**, then click **Add to bundle** (**Add to another bundle** on a row already in one) in the gateway's row of the **Gateways** table. |
33| "This role is already connected in the bundle `<bundle>`." or "This token endpoint is already connected in the bundle `<bundle>`." | An AWS role or token endpoint can be connected in only one Access bundle, and this one already is. | To use the connection in more channels, [attach that bundle to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle) instead. To move it, in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, and choose **Delete**. Then connect it again from its own dialog and pick the new bundle. |
3434| "`<name>` already covers `<host>` in this bundle, so Claude would never use this connection for the hosts they share. Change the hosts or choose another bundle." in the **Connect a Google Cloud identity** dialog | Another Google Cloud connection in the bundle you chose already has that host under **Allowed hosts**, whatever its provider or service account. Claude uses the first connection in a bundle whose hosts match a request, so the new connection would never be used for the shared host. A wildcard such as `*.googleapis.com` covers every subdomain but not `googleapis.com` itself. The dialog won't connect until the overlap is gone. | Remove the shared host from the new connection's **Allowed Google hosts**, or choose another bundle. To give the host to the new connection instead, first narrow the existing one: in **Access bundles**, open the bundle's **Credentials** tab, open the **⋮** menu on the connection's row, choose **Edit**, and change **Allowed hosts**. |
3535| "Couldn't connect the gateway. Try again.", "Couldn't add the gateway to the bundle.", "Couldn't connect the role. Try again.", "Couldn't connect the identity. Try again.", "Couldn't register the authorization server. Try again.", or "Couldn't connect the authorization server. Try again." | The request failed for a reason the dialog doesn't name, most often a temporary one. | Try once more. If the message persists, contact your Anthropic account team with the details under [Contact Anthropic](#contact-anthropic). |
3636| "The issuer URL must be an https URL on the same host as the token endpoint. Leave it empty to use the token endpoint as the audience." in the **Connect an authorization server** dialog | The **Issuer URL** value must be an HTTPS URL on the same host as the token endpoint, or empty. The token is only ever presented to that server, so its audience must name that server. | Enter the issuer identifier your authorization server uses, on the token endpoint's host, or clear the field to use the token endpoint as the audience. |
3737| "This token endpoint is already connected. Manage it from the Authorization servers section." in the **Connect an authorization server** dialog | An authorization server with this token endpoint is already connected in one of your organization's Access bundles, and a server can be connected only once. The dialog checks this before it registers anything. | To use the server in more channels, [attach its bundle to each scope](/docs/claude-tag/admins/attach-to-scope#attach-the-bundle). To connect it again, remove it first: in the **Authorization servers** table, click **Remove** in the server's row. |
38| "That address is already connected as a gateway. Enter your authorization server's own addresses, or remove the gateway first." in the **Connect an authorization server** dialog | The token endpoint, or the **Issuer URL** value, is the address of a gateway connected in one of your organization's Access bundles. One address can't be both, because a token sent to the gateway could be replayed to the server as a grant. | Enter the token endpoint and issuer identifier your authorization server publishes. To use that address for the server instead, remove the gateway first: in **Access bundles**, open the bundle that holds the gateway, open its **Credentials** tab, open the **⋮** menu on the gateway's row, and choose **Delete**. Then, in the **Gateways** table under **Federated cloud access**, click **Remove** in the gateway's row. |
38| "That address is already connected as a gateway. Enter your authorization server's own addresses, or remove the gateway first." in the **Connect an authorization server** dialog | The token endpoint, or the **Issuer URL** value, is the address of a gateway connected in one of your organization's Access bundles. One address can't be both, because a token sent to the gateway could be replayed to the server as a grant. | Enter the token endpoint and issuer identifier your authorization server publishes. To use that address for the server instead, remove the gateway first: in **Access bundles**, open the bundle that holds the gateway, open its **Credentials** tab, open the **⋮** menu on the gateway's row, and choose **Delete**. Then, in the **Gateways** table under **Federated agent access**, click **Remove** in the gateway's row. |
3939| "That address is registered by a connected authorization server. Enter your gateway's address, or remove the server first." in the **Connect a gateway** dialog | The address you entered is a connected authorization server's token endpoint or audience, for example a server whose **Issuer URL** is the bare host `https://auth.example.com`. One address can't be both, because a token sent to the gateway could be replayed to that server as a grant. | Enter the host your gateway answers on. To use that address for a gateway instead, remove the server first: in the **Authorization servers** table, click **Remove** in the server's row. |
4040| "That address is already a connected authorization server's audience. Enter this server's own issuer URL." in the **Connect an authorization server** dialog | The **Issuer URL** value (or the token endpoint, when **Issuer URL** is empty) is already another connected authorization server's audience or token endpoint. Two servers can't share an audience, because a token minted for one would be valid at the other. | In the **Issuer URL** field, enter the issuer identifier this server publishes. If the other server holds this identifier by mistake, remove that server first: in the **Authorization servers** table, click **Remove** in its row, then connect it again with its own issuer URL. |
4141| "The address is too long. Issuer URLs have at most 256 characters." under the **Issuer URL** field of the **Connect an authorization server** dialog | The **Issuer URL** field accepts at most 256 characters, the same limit as the **Token endpoint** field. | Check that the field holds only the issuer identifier, for example `https://auth.example.com`, and not a longer value pasted by mistake. |
from line 69
6969
7070### Removing and reconnecting a gateway
7171
72In the **Gateways** table, click **Remove** in the gateway's row. Claude stops using the gateway at once. A connection that used the gateway stays in its Access bundle but stops working, and Claude reports [request blocked: this credential's audience isn't registered as a gateway for this organization](#request-blocked-this-credential%E2%80%99s-audience-isn%E2%80%99t-registered-as-a-gateway-for-this-organization) until the gateway is registered again.
72In the **Gateways** table, click **Remove** in the gateway's row and confirm with **Remove gateway**. Claude stops using the gateway at once. A connection that used the gateway stays in its Access bundle but stops working, and Claude reports [request blocked: this credential's audience isn't registered as a gateway for this organization](#request-blocked-this-credential%E2%80%99s-audience-isn%E2%80%99t-registered-as-a-gateway-for-this-organization) until the gateway is registered again.
7373
74To reconnect, click **Connect a gateway** in the **Gateways** section and enter the same address. Registering the address restores the existing connection, which is still in the bundle, so don't add it to the bundle again; the dialog refuses if you try.
74To reconnect, click **Connect a gateway** in the **Gateways** section and enter the same address. Registering the address restores the existing connection, which is still in the bundle; the bundle step then offers only bundles the gateway isn't in.
7575
7676## Errors Claude reports in the thread
7777
from line 366
366366
367367## Related resources
368368
369* [Federated cloud access overview](/docs/claude-tag/admins/federated-access/overview): how the token works and which connection type to use
369* [Federated agent access overview](/docs/claude-tag/admins/federated-access/overview): how the token works and which connection type to use
370370* [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway): the setup steps and the connection check in full
371371* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference): every claim, the lifetime, and key rotation
372372* [Limits](/docs/claude-tag/admins/federated-access/limits): counts, lengths, and lifetimes
373* [Troubleshoot Claude Tag setup](/docs/claude-tag/admins/troubleshooting): errors outside federated cloud access
373* [Troubleshoot Claude Tag setup](/docs/claude-tag/admins/troubleshooting): errors outside federated agent access
374374
No line in this hunk matches that.