orderly-sdk-debugging

name	orderly-sdk-debugging
description	Debug and troubleshoot common issues with the Orderly SDK including errors, WebSocket issues, authentication problems, and trading failures.

Orderly Network: SDK Debugging

A comprehensive guide to debugging common issues, handling errors, and troubleshooting problems with the Orderly SDK.

When to Use

• Fixing build errors
• Debugging WebSocket connections
• Handling API errors
• Troubleshooting authentication issues
• Investigating trading failures

Prerequisites

• Orderly SDK installed
• Basic debugging knowledge
• Browser DevTools familiarity

1. Build & Setup Errors

Buffer is not defined

Uncaught ReferenceError: Buffer is not defined

Cause: Wallet libraries use Node.js built-ins (Buffer, crypto) that don't exist in browsers.

Solution: Add vite-plugin-node-polyfills:

npm install -D vite-plugin-node-polyfills

// vite.config.ts
import { nodePolyfills } from 'vite-plugin-node-polyfills';

export default defineConfig({
  plugins: [
    react(),
    nodePolyfills({
      include: ['buffer', 'crypto', 'stream', 'util'],
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
    }),
  ],
});

CSS Import Not Found

ENOENT: no such file or directory, open '@orderly.network/trading/dist/styles.css'

Cause: Only @orderly.network/ui has a CSS file.

Solution: Only import from @orderly.network/ui:

/* Correct - only ui package has CSS */
@import '@orderly.network/ui/dist/styles.css';

/* Wrong - these don't exist */
/* @import '@orderly.network/trading/dist/styles.css'; */
/* @import '@orderly.network/portfolio/dist/styles.css'; */

2. Common Error Codes

API Error Codes

Code	Message	Cause	Solution
-1000	Unknown error	Server error	Retry request
-1002	Unauthorized	Invalid/expired key	Re-authenticate
-1003	Too many requests	Rate limit	Implement backoff
-1102	Invalid parameter	Wrong order params	Validate inputs

Order Error Codes

Code	Message	Cause	Solution
-2001	Insufficient balance	Not enough USDC	Deposit more funds
-2002	Order would trigger liquidation	Risk too high	Reduce position size
-2004	Price out of range	Price too far from mark	Adjust limit price
-2005	Order quantity too small	Below minimum	Increase quantity

Withdrawal Error Codes

Code	Message	Cause	Solution
-3001	Insufficient balance	Not enough available	Check unsettled PnL
-3002	Withdrawal amount too small	Below minimum	Increase amount

3. WebSocket Connection

Monitor Connection Status

import { useWsStatus, WsNetworkStatus } from '@orderly.network/hooks';

function ConnectionIndicator() {
  const wsStatus = useWsStatus();

  return (
    <div className="connection-status">
      {wsStatus === WsNetworkStatus.Connected && (
        <span className="text-green-500">● Connected</span>
      )}
      {wsStatus === WsNetworkStatus.Unstable && (
        <span className="text-yellow-500">● Reconnecting...</span>
      )}
      {wsStatus === WsNetworkStatus.Disconnected && (
        <span className="text-red-500">● Disconnected</span>
      )}
    </div>
  );
}

WebSocket Status Values

Status	Description
Connected	WebSocket is connected and working
Unstable	Connection dropped, attempting reconnect
Disconnected	Connection lost, not reconnecting

4. Account State Issues

Check Account State

import { useAccount, AccountStatusEnum } from '@orderly.network/hooks';

function AccountDebugger() {
  const { state, account } = useAccount();

  useEffect(() => {
    console.log('Account State:', {
      status: state.status,
      address: state.address,
      userId: state.userId,
      accountId: state.accountId,
      hasOrderlyKey: !!account?.keyStore?.getOrderlyKey(),
    });
  }, [state, account]);

  // Common issues:
  switch (state.status) {
    case AccountStatusEnum.NotConnected:
      return <p>Wallet not connected</p>;
    case AccountStatusEnum.Connected:
      return <p>Wallet connected, not signed in</p>;
    case AccountStatusEnum.NotSignedIn:
      return <p>Need to sign message to create Orderly key</p>;
    case AccountStatusEnum.SignedIn:
      return <p>Fully authenticated</p>;
  }
}

Common Account Issues

Issue	Cause	Solution
Stuck on "Connected"	User didn't sign	Prompt for signature
Key expired	365-day expiry	Re-authenticate
Wrong network	Testnet vs mainnet	Check networkId
No user ID	Account not registered	Complete signup

5. Order Submission Errors

Validate Before Submit

import { useOrderEntry } from '@orderly.network/hooks';

function OrderDebugger() {
  const { formattedOrder, metaState, helper } = useOrderEntry('PERP_ETH_USDC');

  // Check for validation errors
  if (metaState.errors) {
    console.log('Order Errors:', metaState.errors);
  }

  // Check order readiness
  console.log('Order Ready:', {
    canSubmit: !metaState.errors && formattedOrder,
    maxQty: helper.maxQty,
    estLiqPrice: helper.estLiqPrice,
  });
}

Debug Order Rejection

async function submitOrderWithDebug(order) {
  try {
    const result = await submit();
    console.log('Order submitted:', result);
  } catch (error) {
    console.error('Order failed:', {
      code: error.code,
      message: error.message,
    });

    if (error.code === -2001) {
      console.log('Fix: Deposit more USDC or reduce order size');
    } else if (error.code === -2002) {
      console.log('Fix: Reduce leverage or position size');
    }

    throw error;
  }
}

6. Deposit/Withdrawal Errors

Debug Deposit

import { useDeposit } from '@orderly.network/hooks';

function DepositDebugger() {
  const { deposit, balance, allowance, approve } = useDeposit();

  const handleDeposit = async (amount) => {
    console.log('Deposit Debug:', {
      amount,
      walletBalance: balance,
      currentAllowance: allowance,
      needsApproval: Number(amount) > Number(allowance),
    });

    try {
      if (Number(amount) > Number(allowance)) {
        console.log('Approving USDC...');
        await approve(amount);
      }

      console.log('Depositing...');
      const result = await deposit();
      console.log('Deposit success:', result);
    } catch (error) {
      console.error('Deposit failed:', error);

      if (error.message.includes('user rejected')) {
        console.log('User rejected transaction');
      } else if (error.message.includes('insufficient')) {
        console.log('Insufficient balance or gas');
      }
    }
  };
}

7. Debugging Hooks

Enable Debug Mode

// Log all hook state changes
function useDebugHook(hookName, value) {
  useEffect(() => {
    console.log(`[${hookName}]`, value);
  }, [value, hookName]);
  return value;
}

// Usage
const positions = useDebugHook('positions', usePositionStream().positions);

8. Network Issues

CORS Errors

Access to fetch at 'https://api.orderly.org/...' has been blocked by CORS

Solutions:

1. SDK handles CORS automatically
2. Check you're not calling API directly without SDK

Rate Limiting

// Implement exponential backoff
async function withRetry(fn, maxRetries = 3, baseDelay = 1000) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === -1003 && attempt < maxRetries - 1) {
        const delay = baseDelay * Math.pow(2, attempt);
        console.log(`Rate limited, retrying in ${delay}ms...`);
        await new Promise((resolve) => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
}

9. Error Boundary

Wrap your app with an error boundary:

import { ErrorBoundary } from '@orderly.network/react-app';

// Or create custom:
class OrderlyErrorBoundary extends React.Component {
  state = { hasError: false, error: undefined };

  static getDerivedStateFromError(error) {
    return { hasError: true, error };
  }

  componentDidCatch(error, errorInfo) {
    console.error('Orderly Error:', error, errorInfo);
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="error-fallback">
          <h2>Something went wrong</h2>
          <pre>{this.state.error?.message}</pre>
          <button onClick={() => window.location.reload()}>Reload Page</button>
        </div>
      );
    }
    return this.props.children;
  }
}

10. Debugging Checklist

Order Not Submitting

• Account status is SignedIn?
• Symbol format correct? (e.g., PERP_ETH_USDC)
• Sufficient balance?
• Order quantity above minimum?
• Limit price within range?
• No validation errors in metaState.errors?

Wallet Not Connecting

• WalletConnectorProvider configured?
• Correct wallet adapters installed?
• Chain supported for network?
• User approved connection in wallet?

Data Not Loading

• WebSocket connected?
• Correct networkId (mainnet vs testnet)?
• User authenticated for private data?
• Check browser console for errors?

Deposit/Withdraw Failing

• Correct chain selected?
• USDC approved for deposit?
• Sufficient gas for transaction?
• No pending withdrawals?
• Available balance covers withdrawal?

11. Useful Debug Components

Full State Debugger

function OrderlyDebugPanel() {
  const { state } = useAccount();
  const wsStatus = useWsStatus();
  const { data: accountInfo } = useAccountInfo();

  if (!import.meta.env.DEV) return null;

  return (
    <div className="fixed bottom-4 right-4 bg-black/80 text-white p-4 rounded-lg text-xs">
      <h3 className="font-bold mb-2">Debug Panel</h3>
      <div>Account: {state.status}</div>
      <div>WS: {wsStatus}</div>
      <div>Balance: {accountInfo?.freeCollateral?.toFixed(2)} USDC</div>
    </div>
  );
}

Related Skills

• orderly-sdk-dex-architecture - Provider setup
• orderly-sdk-wallet-connection - Wallet integration
• orderly-api-authentication - Auth flow
• orderly-sdk-install-dependency - Package installation