> For the complete documentation index, see [llms.txt](https://docs.orda.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orda.network/developers/widget/troubleshooting.md).

# Troubleshooting

### Widget Not Rendering

**Problem**: Widget doesn't appear or styles are broken.

**Solution**:

{% stepper %}
{% step %}
Verify you've imported the styles:

```typescript
import '@ordanetwork/sdk/react/styles.css';
```

{% endstep %}

{% step %}
Check browser console for errors.
{% endstep %}

{% step %}
Ensure `OrdaProvider` wraps your component.
{% endstep %}

{% step %}
Verify all peer dependencies are installed.
{% endstep %}
{% endstepper %}

### Authentication Errors

**Problem**: "Failed to get JWT token" or 401 errors.

**Solution**:

{% stepper %}
{% step %}
Check your `.env.local` has correct credentials:

```bash
ORDA_CLIENT_ID=prj_...
ORDA_CLIENT_SECRET=sec_...
```

{% endstep %}

{% step %}
Verify your JWT endpoint is working:

```bash
curl -X POST http://localhost:3000/api/auth/jwt
```

{% endstep %}

{% step %}
Check server logs for error details.
{% endstep %}

{% step %}
Ensure `getToken()` returns correct format:

```typescript
{ jwt: string, expiresAt: number }
```

{% endstep %}
{% endstepper %}

### Wallet Connection Issues

**Problem**: Wallets won't connect or WalletConnect modal doesn't open.

**Solution**:

{% stepper %}
{% step %}
Verify `NEXT_PUBLIC_WALLET_CONNECT_PROJECT_ID` is set.
{% endstep %}

{% step %}
Check projectId is valid (32+ characters).
{% endstep %}

{% step %}
Ensure your domain is allowlisted in WalletConnect Cloud.
{% endstep %}

{% step %}
Try clearing browser cache and reconnecting.
{% endstep %}

{% step %}
Check browser console for WalletConnect errors.
{% endstep %}
{% endstepper %}

### Build Errors

**Problem**: TypeScript errors or build failures.

**Solution**:

{% stepper %}
{% step %}
Ensure peer dependencies match version requirements:

```bash
npm ls react wagmi viem @tanstack/react-query
```

{% endstep %}

{% step %}
Clear node\_modules and reinstall:

```bash
rm -rf node_modules package-lock.json
npm install
```

{% endstep %}

{% step %}
Check TypeScript version (5.0+):

```bash
npx tsc --version
```

{% endstep %}
{% endstepper %}

### Style Conflicts

**Problem**: Widget styles conflict with app styles.

**Solution**:

{% stepper %}
{% step %}
Widget styles are scoped to `.orda-widget`.
{% endstep %}

{% step %}
Import widget styles AFTER your global styles:

```typescript
import './globals.css';
import '@ordanetwork/sdk/react/styles.css'; // After globals
```

{% endstep %}

{% step %}
Use CSS modules or scoped styles for your app.
{% endstep %}
{% endstepper %}

### Token Prices Not Loading

**Problem**: Token prices show as $0 or fail to load.

**Solution**:

{% stepper %}
{% step %}
Check network connectivity.
{% endstep %}

{% step %}
Verify JWT has `quotes:read` permission.
{% endstep %}

{% step %}
Check browser console for API errors.
{% endstep %}

{% step %}
Ensure token addresses are correct.
{% endstep %}

{% step %}
Try refreshing the page.
{% endstep %}
{% endstepper %}

### Debug Mode

Enable debug mode to see detailed logs:

```typescript
<OrdaProvider
  config={{
    getToken: async () => { /* ... */ },
    appKitConfig,
    debug: true, // Enable debug logs
  }}
>
```

Debug logs will show:

* SDK initialization
* Token refresh timing
* API request details
* Error stack traces

***

## Additional Resources

### Documentation

1. **orda Developer Portal**: <https://app.orda.network>
2. **API Documentation**: <https://docs.orda.network>
3. **orda SDK**: <https://www.npmjs.com/package/@ordanetwork/sdk>