Troubleshooting

​

Installation Issues

​

Package Not Found

# Try clearing cache
rm -rf node_modules package-lock.json
npm cache clean --force
npm install @giza/agent-sdk

​

Type Errors

npm install -D typescript @types/node

​

Configuration Issues

​

Environment Variables Not Found

Error: GIZA_API_KEY environment variable is required

1. Create .env file in project root
2. Add required variables:
   Copy

   GIZA_API_KEY=your-api-key
   GIZA_API_URL=https://api.giza.tech
   GIZA_PARTNER_NAME=your-name
   

3. Load with dotenv:
   Copy

   import 'dotenv/config';
   

​

Invalid API Credentials

GizaAPIError: Unauthorized (401)

• Verify GIZA_API_KEY is correct
• Check GIZA_PARTNER_NAME matches your registration
• Ensure GIZA_API_URL is correct
• Contact Giza support to verify credentials

​

Smart Account Issues

​

Invalid Address Format

ValidationError: wallet address must be a valid Ethereum address

• Address must start with 0x
• Must be 42 characters (0x + 40 hex chars)
• Use lowercase or checksum format
• Verify no extra spaces or characters

​

Smart Account Not Found

GizaAPIError: Smart account not found (404)

1. Create smart account first with createSmartAccount()
2. Verify you’re using correct origin wallet
3. Check you’re querying correct chain

​

Activation Issues

​

No Deposits Found

GizaAPIError: No deposits detected in smart account

1. Verify user deposited funds
2. Check transaction is confirmed on-chain
3. Ensure deposited to correct smart account address
4. Verify on correct chain

​

Protocol Not Available

GizaAPIError: Protocol "xyz" not available for token

1. Use getProtocols() to check available protocols
2. Ensure protocol name is spelled correctly
3. Verify protocol supports your token
4. Check protocol is active on your chain

​

Activation Timeout

1. Increase timeout in SDK config:
   Copy

   const giza = new GizaAgent({
     chainId: Chain.BASE,
     timeout: 60000 // 60 seconds
   });
   

2. Check network connectivity
3. Verify backend API is reachable

​

Performance Issues

​

Slow API Responses

• Check your network connection
• Try increasing timeout
• Enable retry for better reliability:
  Copy

  const giza = new GizaAgent({
    chainId: Chain.BASE,
    enableRetry: true
  });
  

• Consider caching responses

​

Rate Limiting

GizaAPIError: Too Many Requests (429)

1. Implement exponential backoff
2. Cache responses when possible
3. Reduce API call frequency
4. Contact Giza for higher rate limits

​

Withdrawal Issues

​

Withdrawal Takes Too Long

• Withdrawals can take 5-15 minutes
• Protocols may have withdrawal queues
• Network congestion affects speed
• Use pollWithdrawalStatus() to track progress
• If > 30 minutes, contact support

​

Withdrawal Stuck in “Deactivating”

1. Check agent status: getWithdrawalStatus()
2. Verify transactions on block explorer
3. Some protocols have withdrawal delays
4. Network congestion can slow processing
5. Contact support if stuck > 1 hour

​

General Debugging

​

Enable Debug Logging

// Log all API calls
const originalFetch = global.fetch;
global.fetch = async (...args) => {
  console.log('API Call:', args[0]);
  const response = await originalFetch(...args);
  console.log('Response:', response.status);
  return response;
};

​

Check SDK Version

npm list @giza/agent-sdk

npm update @giza/agent-sdk

​

Verify Chain ID

console.log('Chain ID:', giza.getChainId());
console.log('Backend URL:', giza.getBackendUrl());

​

Getting Help

1. Check Documentation: Review relevant docs sections
2. Search Issues: Check GitHub issues for similar problems
3. Enable Retry: Try with enableRetry: true
4. Collect Info:
   • SDK version
   • Node version
   • Error messages
   • Steps to reproduce
5. Contact Support:
   • Email: support@gizatech.xyz
   • GitHub: Open an issue
   • Discord: Join community

​

Common Error Reference

​

Best Practices to Avoid Issues

1. ✅ Always validate inputs before SDK calls
2. ✅ Use try-catch for error handling
3. ✅ Implement retry logic for network issues
4. ✅ Cache responses appropriately
5. ✅ Monitor API health in production
6. ✅ Keep SDK updated to latest version
7. ✅ Test on testnet before production
8. ✅ Handle timeouts gracefully