What causes "ssh action: unknown dst node id" in juanfont/headscale?

ssh action: unknown dst node id

Error message

ssh action: unknown dst node id

What it means

Error "ssh action: unknown dst node id" thrown in juanfont/headscale.

Source

Thrown at hscontrol/noise.go:39

	"golang.org/x/net/http2"
	"tailscale.com/control/controlbase"
	"tailscale.com/control/controlhttp/controlhttpserver"
	"tailscale.com/tailcfg"
	"tailscale.com/types/key"
)

// ErrUnsupportedClientVersion is returned when a client connects with an unsupported protocol version.
var ErrUnsupportedClientVersion = errors.New("unsupported client version")

// ErrMissingURLParameter is returned when a required URL parameter is not provided.
var ErrMissingURLParameter = errors.New("missing URL parameter")

// ErrNoAuthSession is returned when an auth_id does not match any active auth session.
var ErrNoAuthSession = errors.New("no auth session found")

// ErrSSHDstNodeNotFound is returned when the dst node id on a Noise SSH
// action request does not match any registered node.
var ErrSSHDstNodeNotFound = errors.New("ssh action: unknown dst node id")

// ErrSSHMachineKeyMismatch is returned when the Noise session's machine
// key does not match the dst node referenced in the SSH action URL.
var ErrSSHMachineKeyMismatch = errors.New(
	"ssh action: noise session machine key does not match dst node",
)

// ErrSSHAuthSessionNotBound is returned when an SSH action follow-up
// references an auth session that is not bound to an SSH check pair.
var ErrSSHAuthSessionNotBound = errors.New(
	"ssh action: cached auth session is not an SSH-check binding",
)

// ErrSSHBindingMismatch is returned when an SSH action follow-up's
// (src, dst) pair does not match the cached binding for its auth_id.
var ErrSSHBindingMismatch = errors.New(
	"ssh action: cached binding does not match request src/dst",
)

View on GitHub (pinned to 565fd254d0)

Solutions

Inspect the wrapped error for the underlying cause and correct the failing condition (ssh action); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (ssh action); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/noise.go:39 when the library encounters an invalid state.

Common situations: An SSH check action referenced a destination node ID that does not exist. Verify the destination node is registered and its ID is current (headscale nodes list).

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/835fcd3c61d3794d. Report an issue: GitHub.