> ## 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.4.2/intro/products/earn/developers/guides/project-setup) for initialization patterns.
  </Accordion>

  <Accordion title="'VAULT_NOT_FOUND' error">
    **Cause:** No vault 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 `fetchSupportedAssets()`
    * Ensure you're using the correct chain ID

    ```ts theme={null}
    // Verify supported assets first
    const assets = await fetchSupportedAssets({
      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:** Vault 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 vault 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.4.2/intro/products/earn/developers/changelog) for breaking changes
4. Contact [support@paxoslabs.com](mailto:support@paxoslabs.com) with details