Troubleshooting

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

Quick Diagnosis

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

// 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.

'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

// 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()
);

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

// Force approval flow for smart wallets
const auth = await prepareDepositAuthorization({
  ...params,
  forceMethod: "approval",
});

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

// Increase slippage for volatile conditions
const prepared = await prepareDeposit({
  ...params,
  slippage: 100, // 1% instead of default 0.5%
});

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

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 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

Enable debug logging

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

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

Check SDK initialization

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

Verify parameters

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

Inspect APIError details

Catch errors and log error.endpoint, error.statusCode, and error.message.

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:

Enable LogLevel.DEBUG and capture full console output
Note the exact error code and message
Check the Changelog for breaking changes
Contact support@paxoslabs.com with details

Getting started

Origin - Branded Stablecoins

Amplify - Stablecoin Earn

Access - Borrow

USDG0

Quick Diagnosis

Error Reference

Common Error Messages

Wallet-Specific Issues

Smart Wallets (Privy Smart Wallet, Alchemy)

EOA Wallets

Debugging Checklist

Common Patterns

Retry with Exponential Backoff

User-Friendly Error Messages

Getting Help

​Quick Diagnosis

​Error Reference

​Common Error Messages

​Wallet-Specific Issues

​Smart Wallets (Privy Smart Wallet, Alchemy)

​EOA Wallets

​Debugging Checklist

​Common Patterns

​Retry with Exponential Backoff

​User-Friendly Error Messages

​Getting Help

Quick Diagnosis

Error Reference

Common Error Messages

Wallet-Specific Issues

Smart Wallets (Privy Smart Wallet, Alchemy)

EOA Wallets

Debugging Checklist

Common Patterns

Retry with Exponential Backoff

User-Friendly Error Messages

Getting Help