Troubleshooting Aperture
Use the following sections to diagnose and resolve common issues with Aperture by Tailscale.
| Symptom | Likely cause |
|---|---|
| Cannot connect using hostname | MagicDNS disabled, wrong URL |
| HTTP 403 error | Aperture role grant missing after network access succeeds |
| Requests blocked or changed by a guardrail | A guardrail blocked or edited a request or response |
| Device becomes unreachable | Key expiry |
| HTTP 429 errors | Quota misconfiguration |
| Mullvad exit nodes | Mullvad IP collision |
| All sessions from same user | Tag-based identity |
| HTTPS connection issues | URL scheme or hostname does not match client requirements |
| Client connection issues | Wrong base URL or missing auth |
| HTTP 405 error | Double /v1 in base URL |
HTTP 404 on /v1/responses or /v1/messages | Missing compatibility flag |
| Web portal access issues | Portal access disabled or no chat-compatible model |
| Connector validation errors | Invalid connector ID, missing protocol, or authentication misconfiguration |
| OAuth 2.0 authorization fails | Expired flow, identity mismatch, or incorrect provider setup |
| HTTP connector returns unexpected errors | 502 for an unreachable upstream, or 405 for an unsupported method |
| HTTP connector returns 403 Forbidden | Missing connectors grant for proxy access |
| Tools from per-user OAuth connector do not appear | Authorization or capability discovery incomplete |
| Missing MCP tools or resources due to connector ID naming | Legacy connector ID contains _ or - |
| Refresh token failure | Authorization renewal needed or transient provider failure |
Client connection issues
If your client cannot connect or you cannot find its requests in Aperture:
- Confirm the base URL in your client configuration matches your Aperture hostname. For most tools, the URL is
http://<aperture-hostname>orhttp://<aperture-hostname>/v1. - Confirm your client has a valid authentication entry. Most tools require a placeholder API key (such as
-) even though Aperture injects the real credentials. - Verify your device can reach Aperture by opening its hostname in a browser. If portal access is disabled for your account, ask an administrator to verify connectivity.
- If you connect from outside your tailnet, confirm the Aperture CLI bridge or
ts-unplugproxy is running and usehttp://localhost:<port-number>instead ofhttp://<aperture-hostname>.
Retry the request and look for it on your Sessions page. Admins can also check the Logs page. If the request appears, the connection works.
For client-specific settings, refer to Set up LLM clients. The Aperture CLI handles base URLs and authentication automatically.
All sessions appear to come from the same user
If you use tag-based identities to authenticate user devices, all LLM sessions from those devices appear to come from the same user. Tailscale tags do not provide per-user identity. They are intended for service account or server device authentication, not individual user authentication. For example, you might use a tag identity for a fleet of PostgreSQL database servers. Refer to the tags topic for more information.
To resolve this issue, make sure that users connect to Aperture from devices associated with their individual Tailscale accounts. After switching to individual accounts, verify that new sessions on the admin dashboard's Logs page display distinct user names. For details on how Aperture resolves identity for tagged nodes, refer to the tagged device identity topic.
HTTPS connection issues
Use the URL scheme required by your client. Most Aperture clients use http://<aperture-hostname> over Tailscale's encrypted network. Claude Desktop requires the gateway's https:// URL and rejects HTTP. Check the client-specific setup instructions rather than changing every client to HTTP. The Aperture CLI configures the appropriate URL for supported clients.
If the hostname does not resolve, MagicDNS might be disabled. Refer to cannot connect to Aperture using hostname.
Cannot connect to Aperture using hostname
If you cannot connect to Aperture using its short hostname (for example, http://<aperture-hostname>), MagicDNS might be disabled in your tailnet. Aperture relies on MagicDNS to resolve its hostname. When MagicDNS is off, the hostname does not resolve, and connection attempts fail.
Do not use tailscale ping to diagnose this issue. tailscale ping succeeds even when MagicDNS is disabled because it routes traffic through DERP relay using the Tailscale IP address directly. Instead, run tailscale dns status to verify that MagicDNS is active, or check the DNS settings page of the Tailscale admin console.
You can also run nslookup <hostname>.<tailnet>.ts.net to test resolution directly. Replace <hostname> with your Aperture hostname. The default is ai, but you might use a custom name. If the generated client configurations show a placeholder URL such as http://your-aperture-host, MagicDNS is likely not enabled.
To resolve this issue, enable MagicDNS in the Tailscale admin console under DNS settings. Refer to the MagicDNS topic for setup instructions. Alternatively, bypass hostname resolution by using the Tailscale IP address directly (for example, http://<tailscale-ip>/ instead of http://<aperture-hostname>/). You can find the Aperture device's IP address on the Machines page of the admin console.
HTTP 403 access denied error
If Aperture responds with HTTP 403 and access denied: no role granted, Aperture received the request but found no grant that assigns the caller a role. Two independent access layers control the request:
- Tailnet access control rule: A rule in the tailnet policy file permits a network connection to the Aperture device. Without this rule, the request does not reach Aperture and cannot cause this error.
- Aperture grant: A grant in the Aperture configuration assigns the caller a
roleofuseroradmin. If network access works, a missing grant or a grant without arolecan cause the 403 response.
If a user has a role but lacks access to the requested model, Aperture returns HTTP 404. For a model alias, check access to its destination, not the alias name.
To find which layer fails, do the following:
- Use the Preview rules in the Tailscale admin console to confirm that the device can reach the Aperture gateway. If it cannot, fix tailnet access first.
- If the request reaches Aperture and returns this 403, check that a grant with a matching
srcassigns the caller arole.
In the Aperture configuration, a grant's src can be a user login, a group, a single tag, or *. Grants in the tailnet policy file that use the tailscale.com/cap/aperture capability also apply. These grants can use any tailnet src selector.
A single-tag src, such as tag:api, matches every device with that tag, including a device with both tag:api and tag:prod. To match only a device with a specific set of tags, use the composite tag identity. This identity is the device's tags in alphabetical order, joined with commas, such as tag:api,tag:prod.
For more information, refer to grant access to models, set up admin access, and tagged device identity. For intermittent 403 errors while you use a VPN, refer to intermittent failures with Mullvad exit nodes. If the 403 message is request blocked by guardrail or response blocked by guardrail, a guardrail blocked the request. Refer to requests blocked or changed by a guardrail.
Requests blocked or changed by a guardrail
Your organization can run guardrails that check requests before they reach the model and responses before they reach your client. A guardrail can block a request or response, or change it. The following symptoms come from a guardrail, not from the model or the client:
- An error with
request blocked by guardrailorresponse blocked by guardrail: A guardrail blocked the request or response. The status is 403 unless the admin sets another. Many agents retry errors, so the same error can repeat several times. - An error with
guardrail hook unavailable(HTTP 503): Aperture couldn't reach a guardrail that must check every request, so it blocked the request. - An answer that says the request was blocked: The guardrail returned its block message as the answer. The message comes from your organization's policy, not from the model.
- The agent runs a different command than the model proposed, or skips one: A guardrail changed or removed the tool call before the agent ran it. The model might mention the mismatch or try the original call again.
- The answer pauses before the agent runs a tool: Aperture holds tool calls until the response finishes and the guardrail decides.
A response that a guardrail blocks still counts toward your usage and quotas, because the provider already generated it.
If you're an Aperture user, contact your Aperture admin. Include the time of the request and the message you received.
If you're an Aperture admin, check the guardrail's own logs for its decision. To keep a record of what guardrails changed or blocked, send revisions to an asynchronous hook. If agents retry a block in a loop, set the hook's block_response to "message". For details, refer to block and failure responses.
Web portal access issues
Check portal access separately from model access:
- Cannot open the web portal: The web portal is available by default, so a grant that sets
enable_portaltofalse(or legacy configurations usingenable_chat_ui: false) is the usual cause. Confirm no grant disables it for the user. - Chat picker is empty: The user can open the web portal but has no chat-compatible model. Confirm the user's
modelsgrant covers at least one model whose provider declares a chat-compatiblecompatibilityflag (anthropic_messages,openai_chat,openai_responses,gemini_generate_content, orgoogle_generate_content). - A granted, chat-compatible model is missing: The model's provider is likely configured in passthrough mode with no fallback
apikey. A passthrough-only provider serves only requests that carry a client credential, so Aperture hides its models from the portal's chat interface even though they still appear in the/v1/modelsendpoint. To make the model available in chat, configure a fallbackapikeyfor the provider. - Expected models are missing: If you curate the picker with
chat_models, only models matching a non-hiddenentry appear. Confirm the model matches an entry.
For setup steps, refer to set up the chat UI.
Aperture device becomes unreachable
If your Aperture gateway becomes unreachable, check whether its device is expired or missing on the Machines page of the Tailscale admin console.
Aperture displays a warning banner in the admin dashboard when a node key is within 7 days of expiring. This banner is visible only to admin users.
If the device has expired or was deleted, contact Tailscale support to restore gateway access. To prevent key expiry, disable it for the Aperture device from the Machines page. Refer to the key expiry documentation for more information.
HTTP 429 rate limit errors
If you receive an HTTP 429 rate limit error when you expect to have access, a quota in the Aperture configuration is likely misconfigured. If Aperture cannot parse a quota configuration, it rejects all requests matching that quota with a 429 error. Common causes include a typo in the quota bucket name, an invalid quota value, or a quota limit set to zero.
Check the Aperture configuration for misspelled quota bucket names and invalid values, then correct them. Refer to the quota configuration topic for the expected syntax. If you do not need custom quotas, remove the quota field entirely to use the default settings. For steps to check and refill budgets, refer to check and refill budgets.
Intermittent failures with Mullvad exit nodes
If you experience intermittent 403 errors or connection failures when accessing Aperture while a Mullvad exit node is active, the cause is an IP address range collision. Tailscale assigns device addresses from the CGNAT range 100.64.0.0/10, and Mullvad also uses addresses in this range. When a Mullvad exit node is active, traffic destined for Tailscale addresses can be misrouted through Mullvad, causing grant evaluation failures that are indistinguishable from grant permission issues.
To confirm this is the cause, disconnect from the Mullvad exit node and retry the connection. If the errors stop, use Tailscale exit nodes instead, or exclude the Tailscale interface from Mullvad's routing configuration if your Mullvad client supports split tunneling.
HTTP 405 error from upstream provider
If every request returns HTTP 405 Method Not Allowed from the upstream provider, the provider's baseurl likely includes a path segment, typically /v1, that duplicates a segment in the request path. Aperture appends the full incoming request path to baseurl, so a baseurl like https://ai-gateway.vercel.sh/v1 produces an upstream URL of https://ai-gateway.vercel.sh/v1/v1/chat/completions.
To resolve this issue, remove the path segment from baseurl. For cloud providers, baseurl should be the API root without /v1. For example, use https://api.openai.com instead of https://api.openai.com/v1. Refer to the provider matrix for the correct baseurl for each provider. For details on how Aperture constructs upstream URLs, refer to how Aperture builds upstream URLs.
HTTP 404 on /v1/responses or /v1/messages
If requests to /v1/responses or /v1/messages return HTTP 404 but /v1/chat/completions works, the provider's compatibility block does not include the corresponding flag. When compatibility is omitted entirely, only openai_chat is enabled by default. The openai_responses and anthropic_messages flags must be set explicitly.
To resolve this issue, add the appropriate flag to the provider's compatibility block:
{
"compatibility": {
"openai_chat": true,
"openai_responses": true,
"anthropic_messages": true
}
}
Set openai_responses to true to enable the /v1/responses endpoint, or anthropic_messages to true to enable /v1/messages. Refer to the compatibility flags topic for the full list of flags.
Connector validation errors
If Aperture rejects a configuration save with a connector error, check the connector definition. The following table lists common validation errors and their causes:
| Error | Cause |
|---|---|
| Invalid connector ID | The connector ID, which is the key under connectors.servers, must match [a-zA-Z][a-zA-Z0-9]*. The ID starts with a letter and contains only letters and digits. |
| Protocol required | Each connector must set "protocol": "mcp" or "protocol": "http". |
| Reserved ID | You cannot use tailscale, internal, or the ID of a system connector, such as aperture. |
| Duplicate ID | A connector ID must be unique across mcp.servers and connectors.servers. |
| Missing auth fields | A bearer_token auth block requires secret. An oauth2_authorization_code auth block requires client_id, auth_url, and token_url. The client_secret field is optional for public clients that use only Proof Key for Code Exchange (PKCE). |
To fix these errors, correct the connector definition and save again. For the full schema, refer to the connectors configuration reference.
OAuth 2.0 authorization fails
An OAuth 2.0 authorization can fail during consent, at the callback, or during token exchange. The page that the user sees depends on where the failure happens:
- The provider rejects the request: The page shows the provider's error code and description.
- The user declines consent: The page reports that the user canceled authorization.
- Aperture rejects the callback or token exchange: The page shows Authorization failed. Only the Aperture server logs show the cause.
The following table lists the causes that Aperture logs and the next action for each:
| Cause | Next action |
|---|---|
| The consent screen was open for more than 15 minutes, or Aperture restarted during the flow. | The user selects Connect again and finishes within 15 minutes. |
| A different user started the flow. | The user selects Connect again and finishes with the same tailnet identity. |
| The callback arrived for a different connector than the one that started the flow. | An admin checks that the provider's redirect URI is the callback URL of this connector. Then the user starts a new flow. |
| The token exchange failed. | An admin compares client_id, client_secret if it is set, and token_url with the provider's OAuth application. Then the user selects Connect again. |
The provider redirected without a code or state parameter. | An admin checks the provider's redirect URI and response type. Then the user selects Connect again. |
If the provider rejects consent, the page shows the provider's error code. An admin uses this code to check auth_url, the scopes, and the required auth_params against the provider's OAuth application.
The callback URL that the provider must use depends on the connector:
- Default:
https://<aperture-hostname>/aperture/auth/<connector-id>/callback. oauth2_dcrconnectors: The shared DCR callback.- Connectors that set
auth.redirect_uri: The configuredredirect_uri.
If the provider does not issue a refresh token, the first authorization works, but the user must reconnect when the access token expires. For Google, an admin sets "access_type": "offline" in auth_params before the user reconnects. For provider setup, refer to set up a per-user OAuth 2.0 connector.
HTTP connector returns unexpected errors
If an HTTP connector returns errors that your application did not cause, check how Aperture handles proxy requests. Aperture passes the upstream's HTTP error responses to the client without changes. The following table lists the errors that Aperture creates itself:
| Response | Cause |
|---|---|
| 502 Bad Gateway | Aperture could not complete the upstream request. The upstream is unreachable or timed out, or it responded with a redirect, which Aperture blocks. Aperture also returns this error if it cannot get credentials, such as for a per-user OAuth caller who has not connected. |
| 502 Bad Gateway (malformed request) | Aperture could not build the request to the upstream server. Check that the connector's url is a valid URL. |
| 400 Bad Request | The request path contains a traversal sequence, such as ... |
| 405 Method Not Allowed | Aperture does not accept the HTTP method. Aperture accepts only GET, HEAD, POST, PUT, PATCH, DELETE, and OPTIONS. |
| 404 Not Found | The connector ID in the path does not match a verified or custom connector, or the caller has no grant on the connector. Built-in connectors and the aperture system connector have no proxy path. |
For a 502 error, check that the connector's url is correct and that the upstream server is running.
For security, Aperture removes the Authorization and Cookie headers from requests and the Set-Cookie header from responses. If the upstream server requires authentication, configure it in the connector's auth block. Do not send credentials in headers.
Aperture limits HTTP connector responses to 50 MB. It cuts off a larger response and does not return an error.
HTTP connector returns 403 Forbidden
An HTTP connector request fails if the caller has no connectors grant for <connector-id>/proxy. The response depends on the caller:
- An admin, or a caller with another grant on the connector:
403 Forbiddenwithaccess denied. - Other callers:
404withconnector not found. This response does not reveal whether the connector exists.
Two other problems cause similar errors:
- The request does not reach Aperture: Check tailnet access.
- The upstream application returns the 403: Check the permissions in that application. An Aperture grant does not fix this error.
If the caller has no proxy grant, ask an admin to add a connectors grant for the intended callers. The following example grants proxy access to the github connector:
{
"grants": [
{
"src": ["*"],
"app": {
"tailscale.com/cap/aperture": [
{"connectors": ["github/proxy"]}
]
}
}
]
}
Replace github with the connector ID, and change src to match the intended callers. Callers also need a grant that assigns a role. Without a role, they receive access denied: no role granted.
This grant permits only requests to the /v1/connectors/<connector-id>/ proxy path. A <connector-id>/** grant permits all current and future categories of the connector. For grant patterns, refer to the connectors reference. To verify access, refer to get started with connectors.
Tools from per-user OAuth connector do not appear
Each user has a separate authorization and a separate tool list for a per-user oauth2_authorization_code or oauth2_dcr connector. If a user's tools do not appear, open the connector under Connectors in Aperture Chat. The connector's state shows the next action:
- Connect: The user selects Connect and gives consent. After consent, Aperture runs tool discovery, which can fail or time out.
- Ready, but tools are missing: The user selects the connector, then selects Refresh tools.
- If the refresh fails, ask an admin to check that the upstream is reachable.
- If the tools are still missing after a refresh, ask an admin to check that the user's grants permit
<connector-id>/tools/<tool-name>.
- Reconnect or Needs reconnect: The user selects Reconnect and gives consent again. If the user must reconnect after each access token expires, ask an admin to check the provider's offline-access settings.
- Temporarily unavailable: Aperture cannot read the authorization state. The user reloads the page later and does not reconnect.
A full tool list does not prove that tool calls work. To verify, try a permitted tool call. For the user procedure, refer to use a connector. For status meanings, refer to connector statuses.
Refresh token failure
If a per-user OAuth connector stops working, check its status in Aperture Chat before you reconnect.
Ready means that the authorization is usable. Aperture has a stored credential, and no token refresh has failed in a way that requires new consent. A tool call can still fail because of an upstream outage, a timeout, or a rate limit. In this case, check the upstream and try again. Do not disconnect.
Reconnect or Needs reconnect means that one of these conditions occurred:
- The access token expired, and no refresh token exists.
- A token refresh failed and requires new consent. For example, the provider revoked the refresh token.
Common causes include the OAuth 2.0 provider revoking the refresh token due to inactivity, the user revoking access from the provider's account settings, or the provider's refresh token lifetime expiring.
To fix this, the user selects Reconnect and gives consent again. For the steps, refer to reconnect when tools stop working. A temporary refresh failure, such as a timeout, does not change the connector's status and does not require the user to reconnect.
An authorization without a refresh token stays Ready until shortly before its access token expires. If the user must reconnect after each access token expires, ask an admin to check the provider's offline-access settings and the connector settings. For Google, auth_params must include "access_type": "offline". For more information, refer to set up a per-user OAuth 2.0 connector.
Missing MCP tools or resources due to connector ID naming
If MCP tools or resources disappear even though the grants match, ask an Aperture admin to check the connector ID. Aperture loads legacy mcp.servers IDs that contain underscores or hyphens. However, it rejects every configuration save while such an ID exists.
Missing grants can cause the same symptoms. These characters can make Aperture check the wrong connector ID:
- Tools: Aperture names tools
<connector-id>_<tool-name>and splits the name at the first underscore. An underscore in the ID can remove tools fromtools/listwithout an error. Atools/callrequest can return the JSON-RPC errorInvalid paramswithunknown tool. A hyphen does not affect tools. - Resources: Aperture names resource URIs
<connector-id>-<resource-uri>and splits the URI at the first hyphen. A hyphen in the ID can remove resources fromresources/listwithout an error. Aresources/readrequest can returnunknown resource. Resource template grants can also fail. An underscore does not affect resources.
To fix an invalid ID, an admin does the following in one configuration save:
- Add an entry under
connectors.serverswith an ID that matches[a-zA-Z][a-zA-Z0-9]*. - Remove the legacy
mcp.serversentry. - Update the grants that use the old ID.
- Rewrite legacy
mcp_resourcesgrants that use URIs as<new-id>/resources/<resource-name>patterns.
After the save, the admin does the following:
- Update client references to the new names.
- Reconnect the clients.
- List tools and resources to verify that the new names appear under the updated grants.
- Try a permitted call.
For more information about the migration, refer to the connectors reference.
Related
These references provide more detail about the interfaces and settings used in troubleshooting:
- Aperture by Tailscale documentation
- Aperture configuration reference
- Supported providers and clients
- Connectors feature guide
- Connectors configuration reference
- Chat interface reference
- Admin dashboard reference
Get help
If the issue persists after following the troubleshooting steps, contact Tailscale support. Include the Aperture version, the relevant configuration with secrets redacted, the error messages, and the steps you tried.