Reference
Troubleshooting
| Symptom | Check |
|---|---|
| Unknown client or invalid redirect | Register the exact client_id and callback scheme/host/port/path |
invalid_client during exchange | X-Auth-Token, registered accountPubkey, member WIF, signed path/body, clock |
| State mismatch | Same browser transaction, unexpired cookie/state, single callback owner; restart instead of bypassing checks |
| PKCE failure | Original verifier, S256 base64url challenge, unchanged redirect URI |
| Userinfo succeeds but app is signed out | Token-only adapter versus session adapter, Set-Cookie, explicit app origin |
| Account API rejects an OAuth token | The endpoint may require a Better Auth session or BRC-104 wallet authentication |
| Social recovery cannot find a backup | Existing linked provider account, durable recovery mapping, correct BAP identity, uploaded ciphertext |
| Backup password fails | Correct file format and exact password; account-password reset does not reset local encryption |
| BAP profile missing | Registered identity versus saved draft versus published overlay record; allow propagation |
| NFT check returns zero | Primary profile's connected BSV wallets, exact origin/collection metadata, upstream indexer availability |
| Certificate or handle endpoint returns 503 | Check the documented rollout state before treating it as a service outage |
| Seed creation option absent | Creation is independently gated; do not replace an existing identity to recover it |
Gather a useful report
Record the URL path (without credential-bearing query strings), HTTP status, timestamp, request ID when provided, package versions, and whether the environment is staging or production. Include a minimal redacted reproduction. Never send a WIF, recovery phrase, backup password, session cookie, access/refresh token, or decrypted backup.
Use the contact page. Keep manual signups, test fixtures, and destructive experiments in staging. A failed lookup must not silently create a new identity or overwrite a working backup.