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 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.");
  }
}

​
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.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 PatternDescriptionResolution
"SDK not initialized"SDK used before initCall initAmplifySDK() at app startup
"Invalid API key" or "API key cannot be empty"API key validation failedCheck key format (pxl_...)
"No vault found for token..."No vault matches paramsVerify yieldType, token, chainId
"does not support EIP-2612 permit"Token lacks permit supportUse approval flow or forceMethod: "approval"

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