> ## Documentation Index
> Fetch the complete documentation index at: https://aomi.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose CLI, widget, environment, and wallet issues with symptom-based checks and practical fixes.

## CLI Issues

**`aomi: command not found`**
Ensure `@aomi-labs/client` is installed globally or the npm global bin directory is in your PATH.

**Stale session state**
Clear `~/.aomi/` to reset all local session state.

## Execution Issues

**Simulation fails**

* Verify the target chain is supported
* Check RPC endpoint availability
* Ensure the wallet has sufficient funds for gas (even on fork)

**Transaction not executing**

* Check that the wallet is connected and has the correct network selected
* Verify the API key has permission for the requested App
* Review simulation output for errors

## UI Integration

**Widget not rendering**

* Confirm Next.js 15 with App Router
* Verify shadcn/ui is initialized (`components.json` present)
* Check `NEXT_PUBLIC_BACKEND_URL` is set correctly
* Ensure the Para provider is configured if using wallet features

**Widget vs Headless**

* Use the widget for quick integration with standard chat UI
* Use the headless library for fully custom designs
* Both share the same backend, so you can switch between them without server changes

## API Issues

**401 Unauthorized**
The caller credential is missing, expired, or bound to another resource. Sign in again or obtain a grant for the exact Agent, Pipeline, or MCP resource. An App selector is not a credential. See [Authentication](/docs/api-reference/authentication).

**403 Forbidden**
The API key does not authorize the requested App. Verify the key is scoped to the correct App.

## Next Steps

* [Transaction pipeline](/docs/concepts/transaction-pipeline): the integration flow end to end
* [API Reference](/docs/reference/api-reference): HTTP API documentation
* [FAQ](/docs/resources/faq): frequently asked questions