# Troubleshooting (/docs/troubleshooting)



Organized by what you see, not by what is wrong, when integrating the Cavos
[embedded wallet](https://cavos.xyz/embedded-wallet)
([embedded wallets](https://cavos.xyz/embedded-wallet),
[embedded wallet SDK](https://cavos.xyz/embedded-wallet)). The cause is usually
somewhere other than where the symptom appears.

## Users suddenly have new, empty wallets [#users-suddenly-have-new-empty-wallets]

**Almost always the `userId` changed.** Addresses are looked up in the registry
by `(userId, appId, chain, network)`. If your auth changes what it reports (an
email where it used to be a primary key, a provider migration that renumbers
users), those users land on a different wallet. Nothing errors: the app works
perfectly, on the wrong accounts.

The same applies to `appId`: change the app ID and users get new wallets.
Switching `environment` does not change addresses. Derive `userId` from something immutable.

<Callout type="info">
  On every chain, `appSalt` is the HKDF salt for the account key. Changing it
  derives a different key and address (a stark key on Starknet, Ed25519 on Solana
  and Stellar) that will not match the registry row: the user cannot unwrap the
  DEK onto the claimed account. Treat it as permanent.
</Callout>

## `redirect_uri is not registered for this app` [#redirect_uri-is-not-registered-for-this-app]

Returned when the URL your app started OAuth from is not on the app's registered
list: &#x2A;*including when the app has no URLs registered at all.** An empty list
rejects rather than allows, because the callback carries a one-time code and
honouring an unregistered URI would hand that code to whoever asked.

Add the exact URL in **Dashboard → App → Settings → Callback URLs**: scheme, host and path
must match, with no trailing slash and no wildcards. Tunnel and preview domains
each count as a separate origin, and a fresh tunnel URL means a fresh
registration. See [Authentication](/docs/auth#google-and-apple).

## `paymasterApiKey` is required for Starknet connections [#paymasterapikey-is-required-for-starknet-connections]

Starknet sponsors both the account deploy and every transaction through the
paymaster, so the key is required rather than optional. Solana and Stellar use a
relayer activated by `appId` instead: a paymaster key there is ignored, and the
development config check flags it as `[unused-paymaster-key]` so it does not sit
in your bundle for nothing.

## Transactions fail with the wallet apparently connected [#transactions-fail-with-the-wallet-apparently-connected]

Check that `status !== "needs-device-approval"`. Both `undeployed` and `ready`
wallets can execute: only `needs-device-approval` blocks it.

A user can be signed in on a device the account has not authorized yet (the
normal state on a second browser), and `execute` will fail until this device restores the MasterDEK. Route
`walletStatus.needsDeviceApproval` to `approveDeviceWithPasskey()` or an enclave
sign-in; see [Multi-device](/docs/multi-device).

<Callout type="info">
  **Don't require `isReady` for execution.** An `undeployed` wallet can execute.
  The first execution deploys the account atomically, then runs the operation.
</Callout>

## Nothing happens when social recovery should run [#nothing-happens-when-social-recovery-should-run]

Four causes, in the order worth checking:

1. **Not enabled for the environment.** `socialRecovery: true` is the client
   half; the environment must also have it enabled in the dashboard. It is off
   by default. A GitHub user recovers only by signing in with GitHub again, so
   your app must still offer it (`'github'` in `modal.providers`, or
   `login('github')`). The same holds for Telegram (`'telegram'` in
   `modal.providers`, or `login('telegram')`).
2. **No `appId`.** The enclave session is scoped to the app; without it the
   feature cannot start. Flagged as `[social-recovery-without-app-id]`.
3. **Your own auth, with no provider token supplied.** If you authenticate users
   yourself, enrolment and recovery do not happen automatically: the SDK never
   sees a provider token. Call `submitSocialRecoveryToken(idToken)` yourself (since 0.2.6 it is not
   accepted for Google and Apple tokens). See
   [With your own auth](/docs/hardware-isolated-recovery#with-your-own-auth).
4. **The creating device never sealed.** The original device keeps working from
   its local wrap, but a new device gets `not_enrolled`. Reconnect once on the
   original device; it reseals, and enrolling is idempotent.

## `id_token issuer … cannot be used for social recovery` [#id_token-issuer--cannot-be-used-for-social-recovery]

You passed your own session JWT rather than the provider's `id_token`. The
enclave verifies against Google's or Apple's published keys, and a token your
auth signed cannot be verified against them, so it is rejected before it is
sent anywhere.

Clerk, Auth0 and Firebase all expose the underlying provider token, usually
behind an explicit call rather than as the default session object.

## `social authentication is too old; sign in again` [#social-authentication-is-too-old-sign-in-again]

The enclave requires the authentication to be under five minutes old, so a
recovery cannot be driven by a token retrieved from an old session. Pass one
straight from a sign-in. If your auth caches tokens, ask it for a fresh one
rather than reusing what it has.

## Errors log as `{}` [#errors-log-as-]

A host whose console JSON-serializes its arguments (notably Capacitor's native
bridge) prints an `Error` as `{}`, because `message` and `stack` are
non-enumerable. The value is not lost, just unprinted: read the message off the
error you caught, or off the status field for background work
(`walletStatus`-level errors and `authError`).

## Hydration or `window is not defined` errors [#hydration-or-window-is-not-defined-errors]

The React bindings are client-only: `@cavos/kit/react` is marked
`'use client'`. In Next.js App Router, the file that renders `<CavosProvider>`
needs `'use client'` at the top, and so does any component calling `useCavos()`.

Wallet state is not available during server rendering by design: the device key
lives in the browser. Gate on `isLoading` for the first paint rather than
expecting an address to be present immediately.

## `this sign-in did not start here` or `does not match this sign-in` [#this-sign-in-did-not-start-here-or-does-not-match-this-sign-in]

From 0.2.6 a Google or Apple login is tied to a one-time secret the SDK creates
when it builds the sign-in URL, kept in `sessionStorage` on web and in memory on
React Native. The callback has to land where that secret is:

* **Web:** finish the login in the same tab and origin that started it. A
  callback opened in another tab, another browser, or a different origin (a
  preview domain, `localhost` vs. a tunnel) has no secret to match.
* **React Native:** the app has to stay alive between opening the browser and
  receiving the deep link. If the OS killed it, start the login again.
* **A stale URL:** each sign-in URL is single-use. Call `getGoogleOAuthUrl()` /
  `getAppleOAuthUrl()` / `getGitHubOAuthUrl()` / `getTelegramOAuthUrl()` right before redirecting rather
  than caching the result.

## Google or Apple login stopped working after a backend update [#google-or-apple-login-stopped-working-after-a-backend-update]

The hosted sign-in endpoints now require the `nonce` that `@cavos/kit` 0.2.6
sends, and no longer serve the legacy `@cavos/react` flow. Upgrade to
`@cavos/kit` 0.2.6 or later.

## Email, GitHub or Telegram sign-in or enclave recovery fails on a kit below 0.6.0 [#email-github-or-telegram-sign-in-or-enclave-recovery-fails-on-a-kit-below-060]

The wire protocol with the recovery enclave changed in `@cavos/kit` 0.6.0 (a
login key replaced the login secret, and only signed releases from v3 are
accepted). Kits below 0.6.0 no longer work against the production enclave for
email, GitHub and Telegram sign-in and for enclave recovery. Upgrade:

```bash title="Terminal"
npm install @cavos/kit@^0.6.1
```

Apps that set a
custom `socialRecovery` / `socialRecoveryAttestation` with only `pcr0` still
pin strictly and will not pick up signed releases, so their pinned PCR0 must
match the enclave you run. See
[The attestation pin](/docs/hardware-isolated-recovery#the-attestation-pin).

## `this wallet's recovery is held by an earlier enclave release` [#this-wallets-recovery-is-held-by-an-earlier-enclave-release]

The full message is `kit/social-recovery: this wallet's recovery is held by an
earlier enclave release. Sign in again to recover it.`, exported as
`SIGN_IN_AGAIN_TO_RECOVER`.

It is expected, and happens once. An email, GitHub or Telegram user is
recovering on a new device, and their recovery record was sealed by an earlier
enclave release than the one they signed in with. Ask them to sign in again
with the same provider: sign-ins in the next hour run on the release that
holds the record, and that one recovers the wallet. See
[One sealing key per release](/docs/hardware-isolated-recovery#one-sealing-key-per-release).

Kits before 0.6.1 do not handle this and fail the recovery instead. Upgrade
with `npm install @cavos/kit@^0.6.1`.

`enclave_release_unavailable` means the release that holds the record is not
running. That is a Cavos-side outage; retry later.

## GitHub sign-in errors [#github-sign-in-errors]

| Message                                                                | Code              | Meaning                                                                                                                                       |
| ---------------------------------------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `GitHub did not accept this sign-in. Try again.`                       | `github_rejected` | GitHub refused the authorization code (denied, expired, or a verifier mismatch). Start the login again.                                       |
| `This sign-in expired. Sign in again.`                                 | `invalid_grant`   | The one-time grant wrapped around the code is stale or reused. Before 0.5.2 the SDK message was `This GitHub sign-in expired. Sign in again.` |
| `kit/auth: the GitHub sign-in URL is not the one this login asked for` | none              | The authorize URL from the backend was not `https://github.com/login/oauth/authorize` with this login's PKCE `code_challenge` and `S256`.     |
| `kit/auth: the GitHub token was not issued by the enclave`             | none              | The token's `iss` was not `https://enclave.cavos.xyz/github`.                                                                                 |

`github_unreachable` is the enclave's code when it cannot reach GitHub. The
hosted `/api/oauth/github/verify` maps that (and other non-rejected enclave
failures) to `enclave_unavailable`. Retry; if it persists, the enclave's
outbound path to `github.com` / `api.github.com` is down.

If GitHub users suddenly have new, empty wallets, check whether the
environment's GitHub OAuth app changed. Identity is per OAuth client ID, so
that is expected; see
[Authentication → GitHub](/docs/auth#bring-your-own-github-oauth-app).

## Telegram sign-in errors [#telegram-sign-in-errors]

| Message                                                                  | Code                | Meaning                                                                            |
| ------------------------------------------------------------------------ | ------------------- | ---------------------------------------------------------------------------------- |
| `Telegram did not accept this sign-in. Try again.`                       | `telegram_rejected` | Telegram refused the code, or its id\_token failed a check. Start the login again. |
| `This sign-in expired. Sign in again.`                                   | `invalid_grant`     | The one-time grant wrapped around the code is stale or reused.                     |
| `kit/auth: the Telegram sign-in URL is not the one this login asked for` | none                | The authorize URL did not carry exactly this login's challenge, nonce and scope.   |
| `kit/auth: the Telegram token was not issued by the enclave`             | none                | The token's `iss` was not `https://enclave.cavos.xyz/telegram`.                    |

`telegram_unreachable` is the enclave's code when it cannot reach
`oauth.telegram.org`. The hosted `/api/oauth/telegram/verify` returns
`telegram_rejected` as is, and other enclave failures as `enclave_unavailable`.

Telegram sign-in arrived in `@cavos/kit` 0.5.2. Kits below 0.6.0 no longer
work with the current enclave; use `^0.6.1`.

If Telegram users suddenly have new, empty wallets, check whether the
environment's bot changed. Identity is per bot, so that is expected; see
[Authentication → Telegram](/docs/auth#bring-your-own-telegram-bot).

To sign in with another Telegram account, see
[Switching Telegram accounts](/docs/auth#switching-telegram-accounts).

## `connect-src` blocks enclave release lookup [#connect-src-blocks-enclave-release-lookup]

The SDK may fetch `{backendUrl}/api/enclave/releases/{pcr0}` and,
if the bundled Sigstore trusted root is stale, the TUF CDN at
`https://tuf-repo-cdn.sigstore.dev/`. A strict Content-Security-Policy that
omits those hosts fails closed with
`kit/social-recovery: the enclave release lookup failed (<status>)` or
`kit/nitro: the enclave release signature is not valid: <reason>`. Allow both. The hosted
vault already uses `connect-src 'self' https:`.

## Reserve refused to sign, or `token_not_allowed` [#reserve-refused-to-sign-or-token_not_allowed]

That is [`@cavos/reserve`](/docs/reserve), not the kit Stellar relayer. The SDK
compares the built transaction against the request **you** made and refuses to
sign on mismatch.

Typical causes:

* `maxSend` / `maxSendStroops` missing or too tight (`path_moved`, or
  `ReserveError` from the client before a request is sent).
* Fee token not on this host's allowlist: call `reserve.tokens()`. An asset
  **code** is not an identity; use `CODE:ISSUER`.
* Calling `/v1/build` and signing the bytes instead of `send`.
* Quote expired (\~60 seconds): `quote_expired`.
* Creating a new account while another bootstrap is in flight:
  `503 bootstrap_busy`. Retry.

Kit `wallet.execute` on Stellar still uses the Cavos XLM relayer. Do not mix
the two paths for the same first-create.

## Email sign-in errors [#email-sign-in-errors]

`sendOtp` and `verifyOtp` (and `CavosAuthModal`) surface these messages. A code
expires after 5 minutes and allows 3 attempts; a new one for the same address
can be requested after 60 seconds.

| Message                                                                          | Code                                        | Meaning                                                                                                                               |
| -------------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Enter a valid email address.`                                                   | `invalid_request`                           | The address is malformed.                                                                                                             |
| `kit/auth: this app is not registered with Cavos.`                               | `app_not_found`                             | The `appId` is wrong or unknown.                                                                                                      |
| `This email provider is not supported yet.`                                      | `email_undeliverable`                       | Sign-in codes are delivered to providers whose domain publishes an MTA-STS policy, such as Gmail, Outlook / Hotmail, and Proton Mail. |
| `A code was just sent to this address. Wait a minute before requesting another.` | `code_cooldown`                             | A code was requested less than 60 seconds ago.                                                                                        |
| `Too many attempts. Try again in a few minutes.`                                 | `rate_limited`                              | Rate limit reached.                                                                                                                   |
| `Email sign-in is unavailable right now. Try again later.`                       | `email_unavailable` / `enclave_unavailable` | The code service or the enclave could not be reached.                                                                                 |
| `That code is wrong or has expired. Request a new one.`                          | `code_rejected`                             | Wrong code, expired code, or attempts used up.                                                                                        |

On React Native, `sendOtp` and `verifyOtp` throw an `unsupported` error; use
Google or Apple there. See [Authentication](/docs/auth#email-code).

## The Cavos vault [#the-cavos-vault]

**`kit/vault: add <origin> to this app's allowed web origins in the Cavos dashboard`.**
The page's origin is not registered for the app, so the vault refuses to load.
Add it (scheme, host and port, e.g. `http://localhost:3000`) under the app's
settings. An app with no origins registered cannot embed the vault at all.

**`kit/vault: https://vault.cavos.xyz did not load`.** The iframe never
answered within 15 seconds. Check that nothing on your page blocks framing
`vault.cavos.xyz` (a Content Security Policy with `frame-src` or `child-src`
that omits it), and that the page is served over HTTPS or `localhost`.

**Transfers that used to sign silently now ask, or fail with `kit/vault: this
app's policy does not allow this transaction`.** They are over the app's
limits, or are not a transfer of a listed token (contract calls, token
approvals, signer changes). Check the app's **Approvals** page. The daily total
counts only what was signed without asking, per user, and resets at 00:00 UTC.

**A returning user lands on `needs-device-approval` after upgrading to 0.2.0.**
Keys created before the vault lived in your page's storage, which the vault
cannot read. Every chain restores through the enclave or the passkey, as on a new
device. See
[Cavos vault](/docs/vault#logout-and-storage).

## Still stuck [#still-stuck]

Run the config checks and read what they say: they cover the mistakes above
that are visible from configuration alone:

```ts title="TypeScript"
import { validateCavosConfig, formatConfigProblems } from "@cavos/kit/react";

console.log(formatConfigProblems(validateCavosConfig(config)));
```

`<CavosProvider>` already runs these in development. Calling them yourself is
useful in a setup screen or in CI, where a misconfigured environment is cheaper
to catch than in a user's first login.
