Skip to main content
This guide helps you diagnose and resolve common issues when integrating the Amplify SDK.

​
Quick Diagnosis

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
// 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 for initialization patterns.
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
// 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()
);
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
// Force approval flow for smart wallets
const auth = await prepareDepositAuthorization({
  ...params,
  forceMethod: "approval",
});
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
// Increase slippage for volatile conditions
const prepared = await prepareDeposit({
  ...params,
  slippage: 100, // 1% instead of default 0.5%
});
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
try {
  const tx = await prepareWithdrawTxData(params);
} catch (error) {
  if (error instanceof APIError && error.code === "LIQUIDITY_UNAVAILABLE") {
    // Show user-friendly message
    showError("Withdrawals are temporarily limited. Please try a smaller amount.");
  }
}

​
Error Reference

All SDK functions throw APIError with structured metadata: 
import { APIError } from "@paxoslabs/amplify-sdk";

try {
  const auth = await prepareDepositAuthorization(params);
} catch (error) {
  if (error instanceof APIError) {
    console.log(error.code);       // Error code
    console.log(error.endpoint);   // Function that threw
    console.log(error.statusCode); // HTTP status if applicable
    console.log(error.message);    // Human-readable message
  }
}

​
Error Codes

CodeDescriptionResolution
SDK_NOT_INITIALIZEDSDK used before initCall initAmplifySDK() at app startup
INVALID_API_KEYAPI key validation failedCheck key format (pxl_...)
VAULT_NOT_FOUNDNo vault matches paramsVerify yieldType, token, chainId
PERMIT_NOT_SUPPORTEDToken lacks EIP-2612Use approval flow or forceMethod: "approval"
INSUFFICIENT_ALLOWANCEApproval amount too lowIncrease approval or use permit
LIQUIDITY_UNAVAILABLEVault has withdrawal limitsTry smaller amount or wait

​
Wallet-Specific Issues

​
Smart Wallets (Privy Smart Wallet, Alchemy)

IssueCauseSolution
Permit signing failsSmart contracts cannot sign EIP-712Use forceMethod: "approval"
UserOperation times outBundler congestionIncrease timeout, retry later
Batched transaction revertsOne call in batch failingDebug individual calls separately

​
EOA Wallets

IssueCauseSolution
eth_signTypedData_v4 unsupportedOlder wallet versionUpdate wallet, or force approval
Gas estimation failsSimulation revertedCheck parameters, token balance

​
Debugging Checklist

1

Enable debug logging

import { initAmplifySDK, LogLevel } from "@paxoslabs/amplify-sdk";

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

Check SDK initialization

Ensure initAmplifySDK() completed successfully before any other SDK calls.
3

Verify parameters

  • Token address is checksummed
  • Chain ID matches the network
  • Amount is a valid decimal string (e.g., “100.25”)
4

Inspect APIError details

Catch errors and log error.code, error.endpoint, and error.message.
5

Check transaction status

If a transaction was submitted, verify on block explorer whether it reverted or succeeded.

​
Common Patterns

​
Retry with Exponential Backoff

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

function getUserMessage(error: APIError): string {
  const messages: Record<string, string> = {
    SDK_NOT_INITIALIZED: "Please wait while we connect...",
    VAULT_NOT_FOUND: "This token is not available for the selected strategy.",
    PERMIT_NOT_SUPPORTED: "Please approve the transaction in your wallet.",
    LIQUIDITY_UNAVAILABLE: "Withdrawals are temporarily limited.",
  };
  return messages[error.code] || "An unexpected error occurred.";
}

​
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 for breaking changes
  4. Contact support@paxoslabs.com with details