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

# Troubleshooting

> Common issues, error codes, and solutions for Amplify SDK integration

This guide helps you diagnose and resolve common issues when integrating the Amplify SDK.

## Quick Diagnosis

<AccordionGroup>
  <Accordion title="SDK throws 'SDK_NOT_INITIALIZED'">
    **Cause:** Calling SDK functions before `initAmplifySDK()` completes.

    **Solution:**

    * Ensure `initAmplifySDK()` is called at app startup and awaited
    * In React, use a provider pattern or custom hook
    * Check that the API key environment variable is set

    ```ts theme={null}
    // Correct: await initialization
    await initAmplifySDK('pxl_your_api_key')
    const auth = await prepareDepositAuthorization(params)

    // Wrong: not awaiting
    initAmplifySDK('pxl_your_api_key') // Missing await!
    const auth = await prepareDepositAuthorization(params) // Throws!
    ```

    See [Project Setup](/v0.5.2/intro/products/earn/developers/guides/project-setup) for initialization patterns.
  </Accordion>

  <Accordion title="'VAULT_NOT_FOUND' error">
    **Cause:** No account matches the provided yieldType, token, and chainId combination.

    **Solution:**

    * Verify the token address is correct for the chain
    * Check that the yield type supports the token via `getSupportedAssets()`
    * Ensure you're using the correct chain ID

    ```ts theme={null}
    // Verify supported assets first
    const assets = await getSupportedAssets({
      yieldType: YieldType.CORE,
    })

    // Check if your token is supported
    const isSupported = assets.some(
      (asset) => asset.address.toLowerCase() === tokenAddress.toLowerCase()
    )
    ```
  </Accordion>

  <Accordion title="Permit signature fails or is rejected">
    **Cause:** Token may not support EIP-2612, or wallet doesn't support `eth_signTypedData_v4`.

    **Solution:**

    * The SDK automatically falls back to approval flow
    * For smart wallets, use `forceMethod: "approval"` as they cannot sign permits
    * Check wallet compatibility with typed data signing

    ```ts theme={null}
    // Force approval flow for smart wallets
    const auth = await prepareDepositAuthorization({
      ...params,
      forceMethod: 'approval',
    })
    ```
  </Accordion>

  <Accordion title="Transaction reverts on deposit">
    **Cause:** Insufficient balance, allowance, or slippage exceeded.

    **Solution:**

    * Verify user has sufficient token balance
    * Check that approval transaction confirmed before deposit
    * Increase slippage tolerance if market conditions are volatile

    ```ts theme={null}
    // Increase slippage for volatile conditions
    const prepared = await prepareDeposit({
      ...params,
      slippage: 100, // 1% instead of default 0.5%
    })
    ```
  </Accordion>

  <Accordion title="Withdrawal fails with liquidity error">
    **Cause:** Account may have temporary withdrawal limits.

    **Solution:**

    * Try a smaller withdrawal amount
    * Wait and retry during different market conditions
    * Surface the `endpoint` and `statusCode` from `APIError` to understand the specific failure

    ```ts theme={null}
    try {
      const tx = await prepareWithdrawal(params)
    } catch (error) {
      if (error instanceof APIError) {
        console.error(`Withdrawal failed [${error.endpoint}]: ${error.message}`)
        showError(
          'Withdrawals may be temporarily limited. Please try a smaller amount.'
        )
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Error Reference

All SDK functions throw `APIError` with structured metadata:

```ts theme={null}
import { APIError } from '@paxoslabs/amplify-sdk'

try {
  const auth = await prepareDepositAuthorization(params)
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.endpoint) // Function that threw (e.g., "prepareDepositAuthorization")
    console.log(error.statusCode) // HTTP status if applicable
    console.log(error.message) // Human-readable error description
  }
}
```

### Common Error Messages

| Error Message Pattern                              | Description                | Resolution                                     |
| -------------------------------------------------- | -------------------------- | ---------------------------------------------- |
| `"SDK not initialized"`                            | SDK used before init       | Call `initAmplifySDK()` at app startup         |
| `"Invalid API key"` or `"API key cannot be empty"` | API key validation failed  | Check key format (`pxl_...`)                   |
| `"No vault found for token..."`                    | No account matches params  | Verify yieldType, token, chainId               |
| `"does not support EIP-2612 permit"`               | Token lacks permit support | Use approval flow or `forceMethod: "approval"` |

## Wallet-Specific Issues

### Smart Wallets (Privy Smart Wallet, Alchemy)

| Issue                       | Cause                               | Solution                          |
| --------------------------- | ----------------------------------- | --------------------------------- |
| Permit signing fails        | Smart contracts cannot sign EIP-712 | Use `forceMethod: "approval"`     |
| UserOperation times out     | Bundler congestion                  | Increase timeout, retry later     |
| Batched transaction reverts | One call in batch failing           | Debug individual calls separately |

### EOA Wallets

| Issue                              | Cause                | Solution                         |
| ---------------------------------- | -------------------- | -------------------------------- |
| `eth_signTypedData_v4` unsupported | Older wallet version | Update wallet, or force approval |
| Gas estimation fails               | Simulation reverted  | Check parameters, token balance  |

## Debugging Checklist

<Steps>
  <Step title="Enable debug logging">
    ```ts theme={null}
    import { initAmplifySDK, LogLevel } from "@paxoslabs/amplify-sdk";

    await initAmplifySDK("pxl_your_api_key", {
    logLevel: LogLevel.DEBUG,
    });

    ```
  </Step>

  <Step title="Check SDK initialization">
    Ensure `initAmplifySDK()` completed successfully before any other SDK calls.
  </Step>

  <Step title="Verify parameters">
    * Token address is checksummed
    * Chain ID matches the network
    * Amount is a valid decimal string (e.g., "100.25")
  </Step>

  <Step title="Inspect APIError details">
    Catch errors and log `error.endpoint`, `error.statusCode`, and `error.message`.
  </Step>

  <Step title="Check transaction status">
    If a transaction was submitted, verify on block explorer whether it reverted or succeeded.
  </Step>
</Steps>

## Common Patterns

### Retry with Exponential Backoff

```ts theme={null}
async function withRetry<T>(
  fn: () => Promise<T>,
  maxRetries = 3
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise((r) => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }
  throw new Error("Max retries exceeded");
}

// Usage
const auth = await withRetry(() => prepareDepositAuthorization(params));
```

### User-Friendly Error Messages

```ts theme={null}
function getUserMessage(error: APIError): string {
  if (error.message.includes('not initialized')) {
    return 'Please wait while we connect...'
  }
  if (error.message.includes('No vault found')) {
    return 'This token is not available for the selected strategy.'
  }
  if (error.message.includes('not support EIP-2612')) {
    return 'Please approve the transaction in your wallet.'
  }
  return 'An unexpected error occurred. Please try again.'
}
```

## Getting Help

If you've tried these steps and still have issues:

1. Enable `LogLevel.DEBUG` and capture full console output
2. Note the exact error code and message
3. Check the [Changelog](/v0.5.2/intro/products/earn/developers/changelog) for breaking changes
4. Contact [support@paxoslabs.com](mailto:support@paxoslabs.com) with details