Tailscale SSH requires an additional check: why ssh, scp hang
Tailscale SSH check mode: what the sign-in link means, why scp, rsync and scripts hang on it, how to pass or relax it, and the 'does not permit' errors.
“# Tailscale SSH requires an additional check.” means the Tailscale SSH rule that matched your connection is in check mode, and the session waits until you sign in again in a browser at the link printed under it. Once you do, connections go through without asking again for 12 hours by default. The prompt is an SSH banner, so anything that runs ssh without showing you its standard error, or at a log level below INFO, never shows the link and just hangs. Run one ordinary ssh from the same device and pass the check, then retry; for a machine that has to connect unattended, change that rule to accept or give it a longer checkPeriod, each of which gives up some of what the check protects. “tailscale: tailnet policy does not permit you to SSH to this node” is different: no SSH rule in the tailnet policy matches your device and this server, and the fix is adding one.
What you see
In a terminal, the check looks like this, with a different code at the end of the link each time:
$ ssh me@agent-server
# Tailscale SSH requires an additional check.
# To authenticate, visit: https://login.tailscale.com/a/1a2b3c4d5e6fCopiedThose two lines come from Tailscale’s coordination server, not from the client on either machine, which is why users quote them the same way in Tailscale’s issue tracker and its forum. The refusals come from the SSH service Tailscale runs on the server, and in its source (version 1.104.7, November 2026) each is printed with a tailscale: prefix:
- “tailscale: tailnet policy does not permit you to SSH to this node” No SSH rule matches this source and this server, or the tailnet has no SSH rules at all.
- “tailscale: tailnet policy does not permit you to SSH as user "root"” A rule matches the source and the server, but the login you asked for is not in its
users. - “tailscale: failed to look up local user "alice"” The policy allows the login, but no such account exists on the server. Tailscale only uses accounts that already exist; it does not create them.
- “tailscale: failed to fetch next SSH action” By the source, what a pending check ends in when the server stops waiting for it, after about 30 minutes.
What check mode is
Every rule in the ssh section of a tailnet policy has an action: accept lets the connection in on the strength of the device already being signed in to the tailnet, and check first asks the person to “sign in again with their identity provider,” which can include its multi-factor prompt (Tailscale SSH). The sign-in happens on the device that started the connection, through the link the connection prints.
How long a passed check lasts is the rule’s checkPeriod: 12 hours if the rule does not set one, anything from one minute to 168 hours, or always for a check on every connection. With the default, Tailscale’s docs say that once you pass, you “can access the device and any other device in the tailnet without re-verification for the next 12 hours”.
Many people meet check mode without having chosen it. The SSH rule in Tailscale’s default policy, which a new or unedited tailnet still has, lets each person into their own devices, as root or any other user, in check mode. A server you signed in to Tailscale with your own account is one of your own devices, so it asks every 12 hours.
Why scp, rsync or a script just hangs
The prompt reaches your machine as an SSH banner, the text a server may send before login. OpenSSH’s client prints a banner to standard error, and only when its log level is INFO or higher; that is the condition in its source. Meanwhile the connection itself stays open, waiting for the sign-in. So the link goes missing in three ordinary ways:
- A quiet log level.
ssh -q,scp -q(which passes-qon to ssh), orLogLevel ERRORorQUIETin~/.ssh/configsuppress banners. The reporter of the issue above found exactly this: their config logged only errors, and settingLogLevel INFObrought the link back. - Nobody reading standard error. A cron job, a deploy script, a CI step, an agent’s shell command or an editor’s remote connection runs ssh for you, and you see the link only if that program shows you ssh’s standard error.
- A check on every connection. With
checkPeriodset toalways, even a passed check covers nothing after it, and Tailscale’s docs warn that it “may cause unexpected behavior with automation tools that open many SSH connections in a short time span, such as Ansible.”
Plain scp and rsync in a terminal print the banner like ssh does, so if you are at the keyboard, look above the place where the command seems stuck. If nothing is there, ssh -v shows it.
Pass the check, then retry
- Stop the stuck command.
- From the same device, run an ordinary
sshto the server in a terminal. - Open the link and sign in; the waiting
sshthen logs in. - Rerun the command that hung. It goes through for as long as the check period lasts.
The check is made on the device that connects, so passing it in a terminal covers an app on the same computer too; that is how Claude’s and Codex’s desktop apps over SSH get through it. Users report one more snag (issue 22011, October 2026, open): with more than one tailnet in the browser, the link says “This authentication link could not be located. It may have expired.” until the browser is switched to the tailnet the connection belongs to.
Stop it for a machine that connects unattended
When the connection is made by something with no person to sign in, such as a backup job, a deploy from another server, or an agent on one machine reaching another, the check never passes on its own. The way out is in the rule that matches, edited on the admin console’s Access controls page. A narrow rule placed for just that connection is better than loosening a broad one. Two choices:
- A longer
checkPeriod. The person still signs in, but up to once a week instead of twice a day. What it gives up: the check exists so that a device which is stolen, or running something hostile while you are signed in, cannot open a shell on the server without a fresh sign-in, and a longer period leaves a longer window after each one. accept. No sign-in at all: being on the tailnet as a matching source is enough. What it gives up: that same protection, entirely, for every source the rule names. Limitsrcto the one device or tag that needs it andusersto the one login it uses. If the connecting machine is tagged, this is the only choice, because an SSH rule from a tagged device cannot be in check mode.
A rule with a week-long check, for your own devices into a server tagged tag:agent-server, as one non-root login:
{
"action": "check",
"checkPeriod": "168h",
"src": ["autogroup:member"],
"dst": ["tag:agent-server"],
"users": ["deploy"]
}CopiedAnd one that lets a tagged backup machine in without a check, as one login only:
{
"action": "accept",
"src": ["tag:backup"],
"dst": ["tag:agent-server"],
"users": ["backup"]
}CopiedBoth go in the ssh list of the policy file; the policy file reference lists the fields. A tag has to be defined in tagOwners first, and the connecting machine also needs a network rule to the server on port 22 (below). How to lay out the whole policy for a server an agent runs on, so it can be reached but cannot reach back, is Tailscale SSH for an AI agent’s server.
When the policy refuses instead
Tailscale lets an SSH connection through only when the policy file has both a network rule from the source to the server on port 22 and an SSH rule for the source, the server and the login. The refusal message tells you which part matched:
- “does not permit you to SSH to this node”: no SSH rule pairs your device’s
srcwith this server’sdst. The usual cause is a server that was tagged: the default rule’sautogroup:selfcovers only devices owned by a person, never tagged ones, so a tagged server needs a rule naming its tag indst. A source that is itself tagged is likewise matched only by a rule naming its tag insrc. - “does not permit you to SSH as user …”: the rule exists but its
userslist leaves out that login.autogroup:nonrootmeans every login except root, and root has to be listed by name. - “failed to look up local user …”: the policy is fine and the account is missing on the server; create it there or connect as one that exists.
All three come from Tailscale’s SSH service on the server, so seeing one means the connection reached it and the network rule allowed it. If the network rule is what is missing, the server never answers, and you get no Tailscale message at all, only an ssh that waits and times out. A refusal is a banner like the check, so -q or a quiet LogLevel hides it too, and the connection simply closes.
If ssh reaches an ordinary SSH server or nothing at all, check that Tailscale SSH is switched on there: Tailscale’s docs give sudo tailscale set --ssh on the server. Adding --ssh to tailscale up on a server already running with other settings stops with “changing settings via ‘tailscale up’ requires mentioning all non-default flags”, which has a guide of its own.