NeuronAgent Troubleshooting

Common Issues

This guide covers common issues and their solutions when using NeuronAgent.

Connection Problems

Cannot connect to NeuronAgent API

• Verify NeuronAgent is running: curl http://localhost:8080/health
• Check API key is correct and has proper permissions
• Verify database connection string is correct
• Check firewall settings and port availability

WebSocket connection fails

• Verify WebSocket endpoint is accessible
• Check for proxy or load balancer WebSocket support
• Verify CORS settings allow WebSocket connections

Performance Issues

Slow agent responses

• Check LLM API response times
• Review memory search performance and index configuration
• Optimize tool execution and reduce tool calls
• Monitor database query performance

High memory usage

• Review session cleanup policies
• Optimize memory promotion settings
• Check for memory leaks in custom tools

Memory Issues

Memory search returns no results

• Verify memory has been created and indexed
• Check vector dimensions match between query and stored vectors
• Review similarity threshold settings
• Verify NeuronDB extension is properly configured

Memory not persisting

• Check database connection and permissions
• Verify memory promotion worker is running
• Review memory storage configuration

Tool Errors

Tool execution fails

• Verify tool is registered and available
• Check tool permissions for the agent
• Review tool input validation and parameters
• Check tool execution logs for detailed errors

Custom tool not working

• Verify tool registration JSON schema is valid
• Check tool execution function is properly implemented
• Review tool error handling and return values