Troubleshooting

Common integration issues and fast fixes.

Revibase popup doesn’t open

Most often, this is a browser popup restriction.

• Trigger signIn / transferTokens from a direct user action (click/tap).

• Avoid calling it during page load.

window is not defined (Next.js / SSR)

Revibase needs browser APIs.

• Call it from a Client Component.

• Avoid calling it on the server.

/.well-known/revibase.json returns 404

Revibase needs to fetch this file from your app domain.

• Ensure it’s served at https://<your-domain>/.well-known/revibase.json.

• Ensure it’s public (no auth).

Backend callback fails

Your backend callback must be reachable and must have PRIVATE_KEY set.

• Confirm the environment variable exists in production.

• Keep PRIVATE_KEY server-side only.

Passkeys fail or don’t appear

Passkeys are WebAuthn.

• Use HTTPS in production.

• Test in a browser with passkey support (Chrome, Safari, Edge).

Local development on http://localhost is not allowed as the authentication provider is unable to fetch the /.well-known/revibase.json file locally.

Channels get stuck (two-device flow)

A channel is a live connection.

• Use subscribeToChannelStatus to drive your UI.

• If the connection drops, call reconnectChannel(channelId).

• Close the channel when done.

See Two-device approvals (channels).