Summary
When an auth key is supplied (TS_AUTHKEY / --auth-key) but no control URL is configured,
connect silently uses the default Tailscale control plane (controlplane.tailscale.com). For a
Headscale-issued key this fails with a misleading error:
auth key rejected by control plane (likely expired, revoked, or single-use already consumed)
tailscale init failed (control=https://controlplane.tailscale.com (default)): tsnet.Up: backend: invalid key: API key does not exist
The key is fine — it's just being sent to the wrong control plane. Worse, the "likely
expired/revoked/consumed" remediation points the user at the wrong fix (regenerating a perfectly
good key) instead of the real cause (missing control URL).
Expected
When an auth key is supplied but no control URL is set, warn explicitly, e.g.:
no control-url configured; using controlplane.tailscale.com (set TS_CONTROL_URL for Headscale).
Optionally detect Headscale-style keys and surface a clearer hint.
Impact
Wastes debugging time and can trigger unnecessary auth-key regeneration. Hit while bringing up a
bridge to a Headscale tailnet from a shell that had not sourced the env which sets TS_CONTROL_URL.
Summary
When an auth key is supplied (
TS_AUTHKEY/--auth-key) but no control URL is configured,connectsilently uses the default Tailscale control plane (controlplane.tailscale.com). For aHeadscale-issued key this fails with a misleading error:
The key is fine — it's just being sent to the wrong control plane. Worse, the "likely
expired/revoked/consumed" remediation points the user at the wrong fix (regenerating a perfectly
good key) instead of the real cause (missing control URL).
Expected
When an auth key is supplied but no control URL is set, warn explicitly, e.g.:
no control-url configured; using controlplane.tailscale.com (set TS_CONTROL_URL for Headscale).Optionally detect Headscale-style keys and surface a clearer hint.
Impact
Wastes debugging time and can trigger unnecessary auth-key regeneration. Hit while bringing up a
bridge to a Headscale tailnet from a shell that had not sourced the env which sets TS_CONTROL_URL.