> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gizatech.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

## Installation Issues

### Package Not Found

```bash theme={null}
# Try clearing cache
rm -rf node_modules package-lock.json
npm cache clean --force
npm install @gizatech/agent-sdk
```

### Type Errors

Ensure you have TypeScript installed:

```bash theme={null}
npm install -D typescript @types/node
```

## Configuration Issues

### Environment Variables Not Found

```
Error: GIZA_API_KEY environment variable is required
```

**Solution:**

1. Create `.env` file in project root
2. Add required variables:
   ```bash theme={null}
   GIZA_API_KEY=your-api-key
   GIZA_API_URL=https://api.giza.tech
   GIZA_PARTNER_NAME=your-name
   ```
3. Load with `dotenv`:
   ```typescript theme={null}
   import 'dotenv/config';
   ```

### Invalid API Credentials

```
GizaAPIError: Unauthorized (401)
```

**Solution:**

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

**Solution:**

* 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)
```

**Solution:**

1. Create smart account first with `giza.createAgent(eoa)`
2. Verify you're using correct EOA wallet
3. Check you're querying correct chain

## Activation Issues

### No Deposits Found

```
GizaAPIError: No deposits detected in smart account
```

**Solution:**

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

**Solution:**

1. Use `giza.protocols(token)` 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

**Solution:**

1. Increase timeout in SDK config:
   ```typescript theme={null}
   const giza = new Giza({
     chain: Chain.BASE,
     timeout: 60000 // 60 seconds
   });
   ```
2. Check network connectivity
3. Verify backend API is reachable

## Performance Issues

### Slow API Responses

**Solution:**

* Check your network connection
* Try increasing timeout
* Enable retry for better reliability:
  ```typescript theme={null}
  const giza = new Giza({
    chain: Chain.BASE,
    enableRetry: true
  });
  ```
* Consider caching responses

### Rate Limiting

```
GizaAPIError: Too Many Requests (429)
```

**Solution:**

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

**Solution:**

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

### Withdrawal Stuck in "Deactivating"

**Solution:**

1. Check agent status: `agent.status()`
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

```typescript theme={null}
// 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

```bash theme={null}
npm list @gizatech/agent-sdk
```

Update to latest:

```bash theme={null}
npm update @gizatech/agent-sdk
```

### Verify Chain

```typescript theme={null}
console.log('Chain:', giza.getChain());
console.log('API URL:', giza.getApiUrl());
```

## Getting Help

If issues persist:

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](mailto:support@gizatech.xyz)
   * GitHub: Open an issue
   * Discord: Join community

## Common Error Reference

| Error Code | Meaning             | Common Cause           |
| ---------- | ------------------- | ---------------------- |
| 400        | Bad Request         | Invalid parameters     |
| 401        | Unauthorized        | Wrong API credentials  |
| 404        | Not Found           | Resource doesn't exist |
| 429        | Rate Limited        | Too many requests      |
| 500        | Server Error        | Backend issue, retry   |
| 503        | Service Unavailable | Temporary outage       |

## Smart Account Issues (Additional)

### Smart Account Creation Fails

Check:

* Origin wallet is a valid Ethereum address (0x + 40 hex chars)
* Chain is supported
* API credentials are correct

### Can't Find Existing Smart Account

Make sure:

* You're using the same EOA as when it was created
* You're querying the correct chain
* The smart account was actually created (check blockchain explorer)

### Deposits Not Showing Up

Verify:

* Transaction was sent to the correct `smartAccountAddress`
* Transaction confirmed on-chain (check explorer)
* You're checking the right chain
* Agent was activated after deposit

## Avoiding Issues

1. Validate inputs before SDK calls
2. Use try-catch for error handling
3. Add retry logic for network issues
4. Cache responses where it makes sense
5. Monitor API health in production
6. Keep the SDK up to date
7. Test on testnet before production
8. Handle timeouts