Diagnose Alisio node connection and pairing failures for Android, iOS, and macOS companion apps. Use when QR/setup code/manual connect fails, local Wi-Fi works but VPS/tailnet does not, or errors mention pairing required, unauthorized, bootstrap token invalid or expired, gateway.bind, gateway.remote.url, Tailscale, or plugins.entries.device-pair.config.publicUrl.
Goal: find the one real route from node -> gateway, verify Alisio is advertising that route, then fix pairing/auth.
Decide which case you are in before proposing fixes:
Do not mix them.
localhost or LAN IPs.If the setup is unclear or the failure report is vague, ask short clarifying questions before diagnosing.
Ask for:
alisio devices list shows a pending pairing requestDo not guess from .
can't connectPrefer alisio qr --json. It uses the same setup-code payload Android scans.
alisio config get gateway.mode
alisio config get gateway.bind
alisio config get gateway.tailscale.mode
alisio config get gateway.remote.url
alisio config get gateway.auth.mode
alisio config get gateway.auth.allowTailscale
alisio config get plugins.entries.device-pair.config.publicUrl
alisio qr --json
alisio devices list
alisio nodes status
If this Alisio instance is pointed at a remote gateway, also run:
alisio qr --remote --json
If Tailscale is part of the story:
tailscale status --json
alisio qr --json success means:
gatewayUrl: this is the actual endpoint the app should use.urlSource: this tells you which config path won.Common good sources:
gateway.bind=lan: same Wi-Fi / LAN onlygateway.bind=tailnet: direct tailnet accessgateway.tailscale.mode=serve or gateway.tailscale.mode=funnel: Tailscale routeplugins.entries.device-pair.config.publicUrl: explicit public/reverse-proxy routegateway.remote.url: remote gateway routeIf alisio qr --json says Gateway is only bound to loopback:
gateway.bind=auto is not enough if the effective QR route is still loopbackgateway.bind=langateway.tailscale.mode=serve or use gateway.bind=tailnetplugins.entries.device-pair.config.publicUrl or gateway.remote.urlIf gateway.bind=tailnet set, but no tailnet IP was found:
If qr --remote requires gateway.remote.url:
If the app says pairing required:
alisio devices list
alisio devices approve --latest
If the app says bootstrap token invalid or expired:
If the app says unauthorized:
gateway.auth.allowTailscale must match the intended flow127.0.0.1, localhost, or loopback-only config: wrong.urlSource; config is not what you think.alisio devices list shows pending requests: stop changing network config and approve first.Reply with one concrete diagnosis and one route.
If there is not enough signal yet, ask for setup + exact app text instead of guessing.
Good:
The gateway is still loopback-only, so a node on another network can never reach it. Enable Tailscale Serve, restart the gateway, run alisio qr again, rescan, then approve the pending device pairing.Bad:
Maybe LAN, maybe Tailscale, maybe port forwarding, maybe public URL.