Troubleshoot federated agent access changedclaude-tag/admins/federated-access/troubleshooting
Nearest release: v2.1.290, published under 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 5 Oct 2026 18:54 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 23 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+22added
Lines−22removed
From line
10
where the diff opens
First seen
10 Sep 2026
this site's first read of the page
Recorded edits13to this page, all time
The whole hunk
from line 10, old and new numbered
/
from line 10
1010>
1111> Federated connections are managed on the [**Federated agent access**](https://claude.ai/admin-settings/claude-tag/federated-cloud-access) page, under **Claude Tag** in the admin settings sidebar. Changing them needs an organization Owner, or an admin with full Claude Tag management permission.
1212
13This 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.md).
13This 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](https://claude.com/docs/claude-tag/admins/federated-access/token-reference.md).
1414
1515First confirm two things that have nothing to do with federation:
1616
17* The connection applies to the channel, as [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes. For a gateway, the scope's custom instructions also [name the gateway's address](/docs/claude-tag/admins/federated-access/connect-a-gateway.md#let-agents-reach-the-gateway), so Claude knows the gateway exists.
18* You tested in a new thread. A thread already running isn't told about a connection added after it started; ask Claude for the service by name, or send [`@Claude !restart`](/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) in that thread.
17* The connection applies to the channel, as [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes. For a gateway, the scope's custom instructions also [name the gateway's address](https://claude.com/docs/claude-tag/admins/federated-access/connect-a-gateway.md#let-agents-reach-the-gateway), so Claude knows the gateway exists.
18* You tested in a new thread. A thread already running isn't told about a connection added after it started; ask Claude for the service by name, or send [`@Claude !restart`](https://claude.com/docs/claude-tag/users/commands#restart-a-stuck-or-wrong-context-session) in that thread.
1919
20If Claude reports that a host isn't allowed before any request is sent, see [Claude says a host isn't allowed](/docs/claude-tag/admins/troubleshooting.md#claude-says-a-host-isn%E2%80%99t-allowed-or-it-can%E2%80%99t-reach-the-internet).
20If Claude reports that a host isn't allowed before any request is sent, see [Claude says a host isn't allowed](https://claude.com/docs/claude-tag/admins/troubleshooting.md#claude-says-a-host-isn%E2%80%99t-allowed-or-it-can%E2%80%99t-reach-the-internet).
2121
2222## Messages in the console
2323
from line 32
3232| A dialog message containing "isn't enabled for your organization yet", or **Federated agent access** is missing under **Claude Tag** in 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. |
3333| "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. An authorization server's audience address, its **Issuer URL** value or its token endpoint, is also registered 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 an authorization server's row, click **Remove** in the server's row of the **Authorization servers** table first, then remove its address from the **Gateways** table. See [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). |
3434| "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. |
35| "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 bundle, and this one already is. | To use the connection in more channels, apply that bundle in more places instead. To move it, delete the connection from its bundle, as [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes. Then connect it again from its own dialog and pick the new bundle. |
36| "`<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's **Allowed hosts** in its **Edit connection** dialog, as [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes. |
35| "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 bundle, and this one already is. | To use the connection in more channels, apply that bundle in more places instead. To move it, delete the connection from its bundle, as [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes. Then connect it again from its own dialog and pick the new bundle. |
36| "`<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's **Allowed hosts** in its **Edit connection** dialog, as [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes. |
3737| "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). |
3838| "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. |
3939| "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 bundles, and a server can be connected only once. The dialog checks this before it registers anything. | To use the server in more channels, apply its bundle in more places. To connect it again, remove it first: in the **Authorization servers** table, click **Remove** in the server's row. |
40| "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 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: delete the gateway's connection from its bundle, as [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes. Then, in the **Gateways** table under **Federated agent access**, click **Remove** in the gateway's row. |
40| "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 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: delete the gateway's connection from its bundle, as [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes. Then, in the **Gateways** table under **Federated agent access**, click **Remove** in the gateway's row. |
4141| "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. |
4242| "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. |
4343| "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 89
8989
9090**What it means**
9191
92Federated connections work only in agent sessions, such as a Slack channel, where Claude acts under your organization's [agent identity](/docs/claude-tag/concepts/agent-identity.md). The request came from a personal session, such as a [direct message](/docs/claude-tag/concepts/agent-identity.md#direct-message-channels) with `@Claude`. A personal session runs under a person's own account and has no agent identity for the token to name.
92Federated connections work only in agent sessions, such as a Slack channel, where Claude acts under your organization's [agent identity](https://claude.com/docs/claude-tag/concepts/agent-identity.md). The request came from a personal session, such as a [direct message](https://claude.com/docs/claude-tag/concepts/agent-identity.md#direct-message-channels) with `@Claude`. A personal session runs under a person's own account and has no agent identity for the token to name.
9393
9494**How to resolve**
9595
from line 107
107107
108108**How to resolve**
109109
110To keep the gateway, register the same address again; see [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). To drop it, delete the connection from its bundle, as [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes.
110To keep the gateway, register the same address again; see [Removing and reconnecting a gateway](#removing-and-reconnecting-a-gateway). To drop it, delete the connection from its bundle, as [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes.
111111
112112### Claude says Google credentials are not enabled for this organization
113113
from line 163
163163
164164**How to resolve**
165165
166Open the connection's **Edit connection** dialog, as [Manage federated connections on the Connectors tab](/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes, and set **Allowed hosts** to only the APIs Claude calls with the returned token, for example `api.example.com`, with no wildcard that covers the token endpoint's host. If the API and the token endpoint share a host, use a different host for one of them, or [remove the server](/docs/claude-tag/admins/federated-access/authorization-server.md#remove-the-server) and connect it again with **Allowed API paths** listed.
166Open the connection's **Edit connection** dialog, as [Manage federated connections on the Connectors tab](https://claude.com/docs/claude-tag/admins/federated-access/overview#manage-federated-connections-on-the-connectors-tab) describes, and set **Allowed hosts** to only the APIs Claude calls with the returned token, for example `api.example.com`, with no wildcard that covers the token endpoint's host. If the API and the token endpoint share a host, use a different host for one of them, or [remove the server](https://claude.com/docs/claude-tag/admins/federated-access/authorization-server.md#remove-the-server) and connect it again with **Allowed API paths** listed.
167167
168168### credential injection temporarily unavailable; retry the request
169169
from line 209
209209
210210**What it means**
211211
212The sign-in worked, but [Agent Proxy](/docs/claude-tag/concepts/agent-identity.md#agent-proxy) couldn't sign the request with the role's credentials, so it never left for AWS. The reason text after the connection name says which of these applies:
212The sign-in worked, but [Agent Proxy](https://claude.com/docs/claude-tag/concepts/agent-identity.md#agent-proxy) couldn't sign the request with the role's credentials, so it never left for AWS. The reason text after the connection name says which of these applies:
213213
214* **A hostname with no usable region.** Agent Proxy reads the AWS service and signing region from the hostname, so the region must be the last label before `amazonaws.com`, as in `service.region.amazonaws.com`, `my-bucket.s3.us-east-1.amazonaws.com`, or `api.ecr.us-east-1.amazonaws.com`. The [AWS SigV4 credential](/docs/claude-tag/admins/connections/custom.md#aws-sigv4) section lists the hostname forms Agent Proxy signs, including the services it signs with no region.
214* **A hostname with no usable region.** Agent Proxy reads the AWS service and signing region from the hostname, so the region must be the last label before `amazonaws.com`, as in `service.region.amazonaws.com`, `my-bucket.s3.us-east-1.amazonaws.com`, or `api.ecr.us-east-1.amazonaws.com`. The [AWS SigV4 credential](https://claude.com/docs/claude-tag/admins/connections/custom.md#aws-sigv4) section lists the hostname forms Agent Proxy signs, including the services it signs with no region.
215215* **A large request to a service other than S3 with no content hash.** When a request has no `x-amz-content-sha256` header, Agent Proxy hashes the body before signing and refuses a body over 1 MB (1,048,576 bytes). The AWS CLI and SDKs add that header for S3 but usually not for other services.
216216* **An S3 upload with signed chunks.** Agent Proxy signs the uploads the AWS CLI and SDKs send by default, including an upload sent in chunks with a checksum trailer. It can't sign an upload whose chunks the client signs one by one, which the CLI and SDKs do only when payload signing is turned on for the profile. The reason text reads `chunked signing (<mode>) is not supported through the proxy`.
217217
from line 241
241241**How to resolve**
242242
243243* **A missing permission.** Grant the IAM permission to the AWS role, the Google Cloud service account, or the federated identity when no service account is named. For AWS, a 403 also makes Claude assume the role again on the next request, so a fix takes effect on the next try.
244* **A Google API that needs an OAuth scope of its own.** A federated connection can't reach that API. To connect Google Drive, Calendar, or Gmail another way, see [Choose OAuth or a service account](/docs/claude-tag/admins/connections/google.md#choose-oauth-or-a-service-account). If a channel gets both that connection and the federated connection, keep the two from covering the same host; see [Which credential wins](/docs/claude-tag/admins/attach-to-scope.md#which-credential-wins).
244* **A Google API that needs an OAuth scope of its own.** A federated connection can't reach that API. To connect Google Drive, Calendar, or Gmail another way, see [Choose OAuth or a service account](https://claude.com/docs/claude-tag/admins/connections/google.md#choose-oauth-or-a-service-account). If a channel gets both that connection and the federated connection, keep the two from covering the same host; see [Which credential wins](https://claude.com/docs/claude-tag/admins/attach-to-scope.md#which-credential-wins).
245245
246246## Rejections in your own logs
247247
from line 253
253253
254254**What it means**
255255
256One of the standard checks is configured with the wrong value. Your gateway's log of the failing check is the fastest route; if it logs nothing, work down the list. The values to compare against are shown in the **Connect a gateway** dialog before you enter an address, as described on [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway.md#copy-the-values-and-deploy-the-gateway).
256One of the standard checks is configured with the wrong value. Your gateway's log of the failing check is the fastest route; if it logs nothing, work down the list. The values to compare against are shown in the **Connect a gateway** dialog before you enter an address, as described on [Connect a gateway](https://claude.com/docs/claude-tag/admins/federated-access/connect-a-gateway.md#copy-the-values-and-deploy-the-gateway).
257257
258258**How to resolve**
259259
from line 325
325325
326326**How to resolve**
327327
328Google records the reason in your Cloud Audit Logs. The Security Token Service API entry covers the token exchange, and, if you named a service account, the IAM Service Account Credentials API entry covers the impersonation. Both are Data Access audit logs, which Google keeps off by default, as described under [Verify the connection](/docs/claude-tag/admins/federated-access/gcp.md#verify-the-connection). If the logs were on and show no entry at the time of the request, the token wasn't issued; see [injection failed](#injection-failed). Otherwise, work through the checks in order.
328Google records the reason in your Cloud Audit Logs. The Security Token Service API entry covers the token exchange, and, if you named a service account, the IAM Service Account Credentials API entry covers the impersonation. Both are Data Access audit logs, which Google keeps off by default, as described under [Verify the connection](https://claude.com/docs/claude-tag/admins/federated-access/gcp.md#verify-the-connection). If the logs were on and show no entry at the time of the request, the token wasn't issued; see [injection failed](#injection-failed). Otherwise, work through the checks in order.
329329
330330| Check | What to confirm |
331331| :- | :- |
from line 368
368368
369369## Related resources
370370
371* [Federated agent access overview](/docs/claude-tag/admins/federated-access/overview): how the token works and which connection type to use
372* [Connect a gateway](/docs/claude-tag/admins/federated-access/connect-a-gateway.md): the setup steps and the connection check in full
373* [Identity token reference](/docs/claude-tag/admins/federated-access/token-reference.md): every claim, the lifetime, and key rotation
374* [Limits](/docs/claude-tag/admins/federated-access/limits.md): counts, lengths, and lifetimes
375* [Troubleshoot Claude Tag setup](/docs/claude-tag/admins/troubleshooting.md): errors outside federated agent access
371* [Federated agent access overview](https://claude.com/docs/claude-tag/admins/federated-access/overview): how the token works and which connection type to use
372* [Connect a gateway](https://claude.com/docs/claude-tag/admins/federated-access/connect-a-gateway.md): the setup steps and the connection check in full
373* [Identity token reference](https://claude.com/docs/claude-tag/admins/federated-access/token-reference.md): every claim, the lifetime, and key rotation
374* [Limits](https://claude.com/docs/claude-tag/admins/federated-access/limits.md): counts, lengths, and lifetimes
375* [Troubleshoot Claude Tag setup](https://claude.com/docs/claude-tag/admins/troubleshooting.md): errors outside federated agent access
376376
No line in this hunk matches that.