Troubleshooting Aperture

Use the following sections to diagnose and resolve common issues with Aperture by Tailscale.

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> or http://<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-unplug proxy is running and use http://localhost:<port-number> instead of http://<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. This happens because Tailscale tags do not provide per-user identity. The intended use of tags is 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 at all, the problem might be that MagicDNS is disabled rather than an HTTPS issue. 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 (ai is the default, but it might be 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 you receive an HTTP 403 error with the message access denied: no role granted, the issue is a missing or misconfigured grant. Aperture uses two independent layers of access control, and both must be configured correctly:

1. tailnet access control rule: A rule in the tailnet policy file that permits network connections to the Aperture device. Without this rule, the connection fails before reaching Aperture.
2. Aperture grant: A grant in the Aperture configuration that assigns a user or group access to specific models and a role. Without a matching grant, Aperture returns a 403 error.

The most common causes are a missing access control rule in the tailnet policy file, a missing grant in the Aperture configuration, or an incorrect src pattern. For step-by-step instructions on configuring Aperture grants, refer to grant access to models and set up admin access. The src field requires an exact match. For tagged devices, the src value must match the exact comma-joined tag string that Aperture generates. Refer to the tagged device identity topic for details on how Aperture matches tagged devices.

To help diagnose this issue, use the Preview rules in the Tailscale admin console to check that the user's device can reach the Aperture gateway. Then check that the Aperture configuration includes a grant with a src pattern matching the connecting user or tag. If the 403 errors are intermittent and correlate with VPN use, refer to intermittent failures with Mullvad exit nodes for a related cause.

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_portal to false (or legacy configurations using enable_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 models grant covers at least one model whose provider declares a chat-compatible compatibility flag (anthropic_messages, openai_chat, openai_responses, gemini_generate_content, or google_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/models endpoint. To make the model available in chat, configure a fallback apikey for the provider.
• Expected models are missing: If you curate the picker with chat_models, only models matching a non-hidden entry 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, the issue is likely a misconfigured quota in the Aperture configuration. Aperture's quota system fails closed: if the quota configuration cannot be parsed, Aperture 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 quota fields and verify that bucket names are spelled correctly and that values are valid. Refer to the quota configuration topic for the expected syntax. To resolve the issue, correct the quota value in the configuration. If you do not need custom quotas, remove the quota field entirely to use the default settings. For step-by-step instructions on checking and refilling 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, this is due to 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-related error, check the connector definition. The following table lists common validation errors and their causes.

To resolve these errors, correct the connector definition in your configuration and save again. Refer to the connectors configuration reference for the full schema.

OAuth 2.0 authorization fails

If an OAuth 2.0 authorization flow fails during the consent screen, callback, or token exchange, the connector's oauth2_authorization_code configuration is incorrect or the flow has expired. The following symptoms indicate the specific failure:

Common scenarios include an incorrect auth_url that points to the wrong provider endpoint, a callback URL mismatch between the connector configuration and the OAuth 2.0 provider's registered redirect URIs, and missing auth_params required by the provider (for example, Google requires "access_type": "offline" to issue a refresh token).

HTTP connector returns unexpected errors

If an HTTP connector returns errors that do not originate from your application logic, the issue is likely related to how Aperture proxies HTTP connector requests. The following table lists common error responses and their causes.

Aperture strips the Authorization, Cookie, and Set-Cookie headers from proxied HTTP connector requests and responses for security. If the upstream server requires authentication, configure it through the connector's auth block rather than passing headers directly.

Aperture enforces a 50 MB response body limit for HTTP connector responses. Responses exceeding this limit are truncated.

HTTP connector returns 403 Forbidden

If an HTTP connector returns 403 Forbidden, the connecting user does not have a connectors grant that permits access to the connector's proxy endpoint. Aperture requires a grant with a pattern matching <connector-id>/proxy or a broader pattern like <connector-id>/**.

To resolve this issue, add a connectors grant to the user's Aperture grant configuration:

{
  "grants": [
    {
      "src": ["autogroup:members"],
      "app": {
        "tailscale.com/cap/aperture": [
          {"connectors": ["github/proxy"]}
        ]
      }
    }
  ]
}

Replace github with the connector ID and adjust the src pattern to match the appropriate users or groups. Refer to the connectors feature guide for details on grant patterns.

Tools from per-user OAuth connector do not appear

If a connector is configured with oauth2_authorization_code authentication and its tools do not appear for a user, the user has not yet authorized the connector. Connectors that use per-user OAuth 2.0 populate their tools lazily: the tool list is empty until the user completes the OAuth 2.0 authorization flow. Each user must individually authorize the connector because the credentials are per-user, not shared.

To resolve this issue, instruct the user to authorize the connector through the Aperture UI. After authorization completes, the connector's tools become available. Refer to the connectors feature guide for instructions on authorizing connectors.

Refresh token failure

If a previously working per-user OAuth connector stops working, the stored refresh token has likely expired, or the OAuth 2.0 provider has revoked it. When this happens, Aperture attempts to refresh the access token. The refresh fails, the connector stops working for that user, and the user must re-authorize the connector to get a new 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. For Google OAuth 2.0 connectors, make sure that auth_params includes "access_type": "offline" to request a refresh token during authorization. Without this parameter, Google issues only a short-lived access token.

To resolve this issue, have the user re-authorize the connector through the Aperture UI. Refer to the connectors feature guide for authorization instructions.

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 relevant configuration with secrets redacted, error messages, and the steps you have tried.