Troubleshooting Guide

Solutions to common issues

Quick Troubleshooting

1.Check the error message carefully - it often indicates the issue
2.Open browser console (F12) and look for error details
3.Search for your error below or use Ctrl+F
4.Follow the solutions step by step
5.If problem persists, check logs section

🔧 Common Issues

Payment Verification Failed

payment

What does it look like?

Error message: 'Payment verification failed' or 'Invalid signature'

Solutions to Try

1.Check that your wallet has sufficient APT balance
2.Ensure you're using the correct network (testnet vs mainnet)
3.Try creating a new session - the previous one may have expired
4.Clear browser cache and localStorage
5.Check that Aptos network is accessible

Debug Info:

Look for 'waitForTransaction timeout' in console

Insufficient Balance

payment

What does it look like?

Error: 'Insufficient balance' when trying to execute agent

Solutions to Try

1.Check your account balance on the dashboard
2.Request testnet APT from the Aptos faucet
3.Verify the agent's cost (hover over agent name)
4.Ensure budget is set to at least agent cost + 0.01 APT for fees

Debug Info:

Transaction rejected by blockchain

Session Expired

auth

What does it look like?

Error: 'Session expired' or 'Invalid session'

Solutions to Try

1.Create a new delegation session
2.Increase session expiry time (default 24 hours)
3.Check that your computer clock is synchronized
4.Try logging out and logging back in

Debug Info:

Check session creation timestamp

Authentication Failed

auth

What does it look like?

Cannot login or 'Authentication failed' error

Solutions to Try

1.Ensure Google is reachable in your region
2.Clear browser cookies and cache
3.Try in an incognito/private window
4.Check that you're using a supported browser
5.Verify that JavaScript is enabled

Debug Info:

Check browser console for CORS or network errors

Agent Not Found

agents

What does it look like?

Error: 'Agent not found' or '404'

Solutions to Try

1.Verify the agent ID is correct
2.Check that the agent is published on the marketplace
3.Refresh the agents list
4.Try searching by capability instead
5.Ensure the agent is available in your region/network

Debug Info:

Check agent discovery API response

Agent Execution Timeout

agents

What does it look like?

Request takes too long or times out

Solutions to Try

1.Some agents may take longer (especially image generation)
2.Increase timeout in your client (default 30 seconds)
3.Check the agent's status on the dashboard
4.Try a simpler request first
5.Contact agent provider if consistently timing out

Debug Info:

Look for 'request timeout' in logs

API Rate Limit Exceeded

api

What does it look like?

Error: '429 Too Many Requests'

Solutions to Try

1.Reduce the frequency of requests
2.Wait a few minutes before retrying
3.Increase request batching if possible
4.Consider upgrading to higher rate limit tier

Debug Info:

Check 'Retry-After' header for wait time

Network Connection Error

network

What does it look like?

Error: 'Cannot connect to server' or 'Network error'

Solutions to Try

1.Check your internet connection
2.Verify the server is accessible
3.Try a different network (WiFi vs mobile)
4.Check if your firewall blocks the connection
5.Try accessing via VPN if blocked in your region

Debug Info:

Check CORS headers in browser network tab

Wallet Connection Issues

wallet

What does it look like?

Cannot connect wallet or 'Wallet not detected'

Solutions to Try

1.Install Aptos Wallet extension or use Keyless (Google)
2.Ensure wallet extension is enabled
3.Try refreshing the page
4.Clear wallet cache if using installed extension
5.Try a different wallet option

Debug Info:

Check browser console for wallet provider errors

OpenAI API Key Error

config

What does it look like?

Error: 'OPENAI_API_KEY not configured'

Solutions to Try

1.Add OPENAI_API_KEY to .env.local file
2.Verify the key is valid (doesn't expire)
3.Check that key has correct permissions
4.Restart development server after updating .env.local
5.Ensure no extra spaces around the key

Debug Info:

Check server startup logs for configuration errors

📚 Additional Resources

Browser Console

Press F12 to open developer tools:

• Click "Console" tab for error messages
• Look for red error messages
• Copy full error text
• Check "Network" tab for API errors

Check Status

Before troubleshooting, verify:

• Internet connection working
• Browser is up to date
• JavaScript is enabled
• Not in incognito mode (if issues)

Server Logs

For development issues:

• Check terminal where dev server runs
• Look for build errors
• Check for missing environment variables
• Verify API connections

Environment Setup

Verify your .env.local:

• OPENAI_API_KEY set correctly
• NEXT_PUBLIC_APTOS_NETWORK set
• No extra spaces around values
• Run: npm install after changes

🔄 If Nothing Works - Reset Steps

1
Clear Browser Cache
Ctrl+Shift+Del (Windows) or Cmd+Shift+Del (Mac)
2
Clear Local Storage
In console: localStorage.clear() then refresh
3
Logout & Login Again
Disconnect wallet and reconnect fresh
4
Restart Dev Server
Kill with Ctrl+C and run: npm run dev
5
Try Fresh Install
rm -rf node_modules && npm install

INITIALIZING

Troubleshooting Guide

Solutions to common issues

Quick Troubleshooting

1.Check the error message carefully - it often indicates the issue
2.Open browser console (F12) and look for error details
3.Search for your error below or use Ctrl+F
4.Follow the solutions step by step
5.If problem persists, check logs section

🔧 Common Issues

Payment Verification Failed

payment

What does it look like?

Error message: 'Payment verification failed' or 'Invalid signature'

Solutions to Try

1.Check that your wallet has sufficient APT balance
2.Ensure you're using the correct network (testnet vs mainnet)
3.Try creating a new session - the previous one may have expired
4.Clear browser cache and localStorage
5.Check that Aptos network is accessible

Debug Info:

Look for 'waitForTransaction timeout' in console

Insufficient Balance

payment

What does it look like?

Error: 'Insufficient balance' when trying to execute agent

Solutions to Try

1.Check your account balance on the dashboard
2.Request testnet APT from the Aptos faucet
3.Verify the agent's cost (hover over agent name)
4.Ensure budget is set to at least agent cost + 0.01 APT for fees

Debug Info:

Transaction rejected by blockchain

Session Expired

auth

What does it look like?

Error: 'Session expired' or 'Invalid session'

Solutions to Try

1.Create a new delegation session
2.Increase session expiry time (default 24 hours)
3.Check that your computer clock is synchronized
4.Try logging out and logging back in

Debug Info:

Check session creation timestamp

Authentication Failed

auth

What does it look like?

Cannot login or 'Authentication failed' error

Solutions to Try

1.Ensure Google is reachable in your region
2.Clear browser cookies and cache
3.Try in an incognito/private window
4.Check that you're using a supported browser
5.Verify that JavaScript is enabled

Debug Info:

Check browser console for CORS or network errors

Agent Not Found

agents

What does it look like?

Error: 'Agent not found' or '404'

Solutions to Try

1.Verify the agent ID is correct
2.Check that the agent is published on the marketplace
3.Refresh the agents list
4.Try searching by capability instead
5.Ensure the agent is available in your region/network

Debug Info:

Check agent discovery API response

Agent Execution Timeout

agents

What does it look like?

Request takes too long or times out

Solutions to Try

1.Some agents may take longer (especially image generation)
2.Increase timeout in your client (default 30 seconds)
3.Check the agent's status on the dashboard
4.Try a simpler request first
5.Contact agent provider if consistently timing out

Debug Info:

Look for 'request timeout' in logs

API Rate Limit Exceeded

api

What does it look like?

Error: '429 Too Many Requests'

Solutions to Try

1.Reduce the frequency of requests
2.Wait a few minutes before retrying
3.Increase request batching if possible
4.Consider upgrading to higher rate limit tier

Debug Info:

Check 'Retry-After' header for wait time

Network Connection Error

network

What does it look like?

Error: 'Cannot connect to server' or 'Network error'

Solutions to Try

1.Check your internet connection
2.Verify the server is accessible
3.Try a different network (WiFi vs mobile)
4.Check if your firewall blocks the connection
5.Try accessing via VPN if blocked in your region

Debug Info:

Check CORS headers in browser network tab

Wallet Connection Issues

wallet

What does it look like?

Cannot connect wallet or 'Wallet not detected'

Solutions to Try

1.Install Aptos Wallet extension or use Keyless (Google)
2.Ensure wallet extension is enabled
3.Try refreshing the page
4.Clear wallet cache if using installed extension
5.Try a different wallet option

Debug Info:

Check browser console for wallet provider errors

OpenAI API Key Error

config

What does it look like?

Error: 'OPENAI_API_KEY not configured'

Solutions to Try

1.Add OPENAI_API_KEY to .env.local file
2.Verify the key is valid (doesn't expire)
3.Check that key has correct permissions
4.Restart development server after updating .env.local
5.Ensure no extra spaces around the key

Debug Info:

Check server startup logs for configuration errors

📚 Additional Resources

Browser Console

Press F12 to open developer tools:

• Click "Console" tab for error messages
• Look for red error messages
• Copy full error text
• Check "Network" tab for API errors

Check Status

Before troubleshooting, verify:

• Internet connection working
• Browser is up to date
• JavaScript is enabled
• Not in incognito mode (if issues)

Server Logs

For development issues:

• Check terminal where dev server runs
• Look for build errors
• Check for missing environment variables
• Verify API connections

Environment Setup

Verify your .env.local:

• OPENAI_API_KEY set correctly
• NEXT_PUBLIC_APTOS_NETWORK set
• No extra spaces around values
• Run: npm install after changes

🔄 If Nothing Works - Reset Steps

1
Clear Browser Cache
Ctrl+Shift+Del (Windows) or Cmd+Shift+Del (Mac)
2
Clear Local Storage
In console: localStorage.clear() then refresh
3
Logout & Login Again
Disconnect wallet and reconnect fresh
4
Restart Dev Server
Kill with Ctrl+C and run: npm run dev
5
Try Fresh Install
rm -rf node_modules && npm install