> For the complete documentation index, see [llms.txt](https://docs.megaeth.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.megaeth.com/moss-docs/core-sdk/error-handling.md).

# Troubleshooting and Common Issues

Use this page to debug integration issues quickly and to answer common support questions.

## Fast Triage Checklist

1. Confirm SDK is initialised once at app boot.
2. Confirm current status with `mega.status()` or `useStatus()`.
3. Confirm app permissions/session grants are active and not expired.
4. Confirm call scope matches `calls[]` entries exactly (`to` + `signature`).
5. Treat user cancellation as neutral, and handle explicit `error` responses separately with retry guidance.

## Common Issues

| Issue                                                | Likely cause                                                      | What to do                                                                                                    |
| ---------------------------------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Wallet iframe is not appearing                       | iframe blocked by CSP, extension policy, or embedding constraints | Check browser console + network tab, verify wallet origin is allowed, and call initialise during app startup. |
| initialise() is not resolving                        | Wallet bridge was blocked or never reached ready state            | Verify iframe load succeeded, avoid duplicate boot logic, and confirm network/config values are valid.        |
| User cancels connect or signing                      | User intentionally dismissed approval flow                        | Treat as cancelled state, preserve UI state, and provide a retry action from explicit user intent.            |
| Status is disconnected after reload                  | Session was not active or not restored yet                        | Check status on load, show reconnect UI, and do not assume connected state after refresh.                     |
| Silent call fails because no valid permission exists | No active session grant for the exact action                      | Grant permissions first, then retry with silent mode only after grant confirmation.                           |
| Permission expired                                   | Current time is past permissions.expiry                           | Request a new session grant with a fresh expiry window.                                                       |
| Spend limit reached                                  | Configured spend cap is exhausted for the period                  | Request a new grant with updated limits only when needed and keep least-privilege scope.                      |
| Contract call rejected due to wrong to/signature     | Granted calls\[] does not match the attempted contract/function   | Use canonical matching with both to + signature and grant the exact required pair.                            |
| Balance query returns empty when disconnected        | No connected account context for balances query                   | Connect first, then query balances. In React, useStatus should be connected before showing balances.          |
| React hooks are not updating                         | MegaProvider is missing or mounted incorrectly                    | Wrap the app in MegaProvider, ensure it mounts once in a stable shell, and confirm initialise completes.      |

## User-Facing Copy Guidance

* Use “Creating your account”.
* Use “Restoring account”.
* Avoid “Restoring Keys” in docs screenshots, captions, and support macros unless referencing legacy UI text.

## Permission Management for Support Teams

* Users can revoke app permissions per app in wallet/account settings.
* App-triggered `revokePermissions()` is supported, but it is not the only revocation path.
* Do not describe revocation as global-only or all-or-nothing.

## Account Recovery Wording

* Use “Recovery Code” or “Account Recovery Code”.
* Avoid “seed phrase”, “backup phrase”, or “recovery phrase” for MOSS account recovery UX.
* Clarify that the Recovery Code is MOSS-specific and cannot be imported into MetaMask or other external wallets.
* Support guidance should frame this as account recovery for MOSS passkey-based setup.

Canonical permission matching is contract + function scope with `{ to, signature }`. Keep session grants narrow, short-lived, and explicit.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.megaeth.com/moss-docs/core-sdk/error-handling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.