![\"Project](\"https://cdn.brandfetch.io/tailscale.com/fallback/lettermark/theme/dark/h/256/w/256/icon?c=1bfwsmEH20zzEfSNTed\")
Last validated: Jan 12, 2026
\nGrants are Tailscale's unified approach to defining access controls for both network and application layers in your Tailscale network (known as a tailnet). This guide walks you through diagnosing and solving common grant-related problems, progressing from basic verification techniques to resolving complex authorization scenarios.
\nThis section covers the tools and methods available for inspecting your grant policies, verifying policy compilation, and examining how the Tailscale policy engine applies permissions to specific devices or users. Using these diagnostic techniques will help you identify the root cause of most grant-related problems.
\nKeep in mind that Tailscale validates the syntax of the tailnet policy file, including the grants section, when you save it. You won't be able to save it if it has a syntax error. This is true for our admin console editor, GitOps, Terraform, and our API. You also won't be able to save the tailnet policy file if it refers to a target (such as a group) that is not defined.
\nThe first step in troubleshooting is to verify that your grants are correctly defined in your tailnet policy file. You can use the Preview rules tab from the Access controls page of the admin console to check how the rules apply to specific users or tags. This can help you ensure the policy configuration will work as you intend it to.
\nwhoisFor diagnosing issues with application layer capabilities granted to specific devices or users, the tailscale whois command is invaluable. This command provides detailed information about a node, including all capabilities granted to it through your tailnet policy.
To inspect the capabilities of a user or device, use its Tailscale IP address:
\ntailscale whois 100.100.123.123\nThe output includes:
\nPay special attention to the Capabilities section of the output, which details all application capabilities granted to the device. Each capability listing includes its full name and parameters, letting you verify that it is applying the correct permissions.
\nMany grant-related issues stem from basic configuration problems or misunderstandings about how grants work. This section addresses some common issues you might encounter when working with grants.
\nSelectors might fail to match the intended targets. This happens when the selectors in your grants don't correctly identify the devices or users you're trying to permit.
\nCommon selector matching problems include:
\ngroup: or tag names with tag:. This type of syntax error will be caught automatically unless there's also a host with the same name as the group or tag.To troubleshoot selector matching issues:
\ntailscale status to verify the tags applied to your devices.You must run this command on each device you're checking.
\nIf you're using autogroups (such as autogroup:member), make sure you understand the devices within each autogroup. For example, autogroup:member includes all users who are members of your tailnet, but not devices shared from other tailnets.
Beyond basic configuration problems, you might encounter more complex issues with grants, especially when implementing sophisticated access control policies (such as posture checks, route filtering, or custom application capabilities). These issues often require a deeper understanding of how the Tailscale policy engine processes and applies grants.
\nvia field routingThe via field in grants lets you segment resource access through different routers based on specific criteria. However, misconfiguration can lead to routing failures or unexpected traffic paths.
Common via routing issues include:
via target that isn't reachable from the source.via target with subnet routers that don't have the appropriate subnet routes advertised.via target with app connectors that have not been appropriately configured.via target with exit nodes that have not been approved.via field when intending to route traffic to subnet routes, app connectors, or exit nodes.To troubleshoot via routing issues:
via field exists and is online using tailscale status.via device has the appropriate configuration.tailscale status --routes.via device is reachable from the source device using tailscale ping.via device by examining logs on the via device.Example of a correct via configuration:
\"grants\": [\\\r\n {\\\r\n \"src\": [\"group:eng\"],\\\r\n \"dst\": [\"192.0.2.0/24\"],\\\r\n \"ip\": [\"*\"],\\\r\n \"via\": [\"tag:subnet-router\"]\\\r\n }\\\r\n]\nYou can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.
\nIn this example, make sure that a device with the tag:subnet-router tag exists, is online, and has the 192.0.2.0/24 subnet route advertised.
The srcPosture field lets you restrict access based on device posture conditions.
Common device posture issues include:
\nTo troubleshoot device posture issues:
\ntailscale status --self to get the device attributes that are checked for posture verification.Example of device posture verification:
\n\"postures\": {\r\n \"posture:latest\": [\\\r\n \"node:tsVersion >= '1.42.0'\",\\\r\n \"node:os == 'linux'\"\\\r\n ]\r\n},\r\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"group:eng\"],\\\r\n \"dst\": [\"tag:prod\"],\\\r\n \"ip\": [\"*\"]\\\r\n \"srcPosture\": [\"posture:latest\"]\\\r\n }\\\r\n]\nYou can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.
\nIf devices are failing posture checks, temporarily remove the srcPosture field to verify that the grant works without posture conditions, then add them back one by one to identify the problematic condition.
Integrating application capabilities with grants can introduce issues when applications don't correctly interpret the capabilities provided by the Tailscale client.
\nCommon application capability issues include:
\nTo troubleshoot application capability issues:
\ntsnet library.Example of a correct application capability grant:
\n\"grants\": [\\\r\n {\\\r\n \"src\": [\"group:eng\"],\\\r\n \"dst\": [\"tag:tailsql\"],\\\r\n \"ip\": [\"tcp:443\"],\\\r\n \"app\": {\\\r\n \"tailscale.com/cap/tailsql\": [\\\r\n {\\\r\n \"dataSrc\": [\"prod\", \"staging\"]\\\r\n }\\\r\n ]\\\r\n }\\\r\n }\\\r\n]\nYou can use the visual policy editor to manage your tailnet policy file. Refer to the visual editor reference for guidance on using the visual editor.
\nIn this example, make sure that the application running on devices with the tag:tailsql tag is correctly checking for the tailscale.com/cap/tailsql capability and properly interpreting the dataSrc parameter.
This section outlines best practices for designing, implementing, and maintaining grants in your tailnet policy. By following these recommendations, you can minimize issues and streamline troubleshooting when problems do arise.
\nip field when appropriate.Following these principles will result in a more maintainable policy file that's less prone to issues and easier to troubleshoot when problems occur.
\nConsider using testing strategies before deploying changes to your grants:
\nBy thoroughly testing changes before deployment and monitoring for issues afterward, you can identify and resolve problems before they affect your users.
\nAsk AI
\nreCAPTCHA
\nRecaptcha requires verification.
\nprotected by reCAPTCHA
\n"}