Concepts
Troubleshooting.
Common failures usually come from unreachable callback URLs, expired requests, or mismatched signature inputs.
| Symptom | Likely cause | Fix |
|---|---|---|
| Delivery failed / Connection failure | The callback URL is unreachable from the phone, Tailscale is asleep, or Android blocks cleartext HTTP. | Use an HTTPS tunnel such as Tailscale Serve, then scan a fresh QR code. |
| QR stays pending | The app did not deliver a callback or delivered it to an old request. | Check the generated callback URL, request id, and server logs. |
| Next dev WebSocket fails on Tailscale URL | Next blocks cross-origin dev assets by default. | Add the Tailscale host to allowedDevOrigins and restart next dev. |
| Signature verification failed | The server verified a different payload, decoded the DID incorrectly, or received an unexpected signature encoding. | Verify the exact stored challenge string and use the official DID/signature helpers. |
| Request expired | The user approved after the short TTL elapsed. | Generate a fresh QR code and keep the TTL visible in the UI. |