Skip to main content

Troubleshooting Guide

This guide covers common issues and solutions when working with Axon OS nodes and workflows.

Common Node Issues​

Node Execution Errors​

Issue: Node fails to execute with timeout error​

Solution:

  • Increase the node timeout in configuration
  • Check if external services are responsive
  • Optimize node logic for better performance

Issue: Invalid input data format​

Solution:

  • Validate input data before processing
  • Use data transformation nodes to convert formats
  • Check node input schema requirements

Issue: Memory errors with large datasets​

Solution:

  • Enable streaming mode for large data processing
  • Process data in smaller chunks
  • Optimize memory usage in custom nodes

Authentication Issues​

Issue: API authentication failures​

Solution:

  • Verify API keys and credentials are current
  • Check token expiration times
  • Ensure proper authentication method is used

Issue: OAuth flow errors​

Solution:

  • Verify redirect URLs are correctly configured
  • Check OAuth application settings
  • Ensure proper scopes are requested

Network and Connectivity​

Issue: Connection timeout errors​

Solution:

  • Check network connectivity
  • Verify firewall settings
  • Increase connection timeout values

Issue: SSL certificate errors​

Solution:

  • Verify certificate validity
  • Update certificate store
  • Configure certificate validation settings

Database Connection Issues​

SQL Database Problems​

Issue: Connection refused​

Solution:

  • Verify database server is running
  • Check connection string format
  • Ensure proper network access

Issue: Query performance issues​

Solution:

  • Add proper database indexes
  • Optimize SQL queries
  • Use connection pooling

NoSQL Database Problems​

Issue: Document validation errors​

Solution:

  • Check document schema requirements
  • Validate data types before insertion
  • Review collection configuration

Workflow Execution Issues​

Flow Control Problems​

Issue: Infinite loops in workflows​

Solution:

  • Add proper exit conditions
  • Set maximum iteration limits
  • Use timeout mechanisms

Issue: Conditional logic not working​

Solution:

  • Verify condition expressions
  • Check data types in comparisons
  • Use debugging nodes to trace values

Performance Issues​

Issue: Slow workflow execution​

Solution:

  • Identify bottleneck nodes
  • Optimize data processing logic
  • Use parallel execution where possible

Issue: High memory usage​

Solution:

  • Process data in smaller batches
  • Clear unused variables
  • Optimize data structures

API Integration Issues​

REST API Problems​

Issue: 429 Rate limit exceeded​

Solution:

  • Implement exponential backoff
  • Reduce request frequency
  • Use caching for repeated requests

Issue: Malformed JSON responses​

Solution:

  • Validate API response format
  • Handle parsing errors gracefully
  • Check API documentation for updates

GraphQL Issues​

Issue: Query syntax errors​

Solution:

  • Validate GraphQL query syntax
  • Check schema documentation
  • Use GraphQL playground for testing

Data Transformation Issues​

Parsing Problems​

Issue: JSON parsing failures​

Solution:

  • Validate JSON syntax
  • Handle malformed data gracefully
  • Use strict parsing mode

Issue: CSV parsing errors​

Solution:

  • Check delimiter and escape characters
  • Handle missing headers
  • Validate column count consistency

Validation Issues​

Issue: Schema validation failures​

Solution:

  • Review schema requirements
  • Check data type compatibility
  • Handle optional fields properly

Security Issues​

Authentication Problems​

Issue: JWT token validation failures​

Solution:

  • Verify token signature
  • Check token expiration
  • Ensure proper secret key

Issue: Encryption/decryption errors​

Solution:

  • Verify encryption algorithm
  • Check key format and length
  • Handle encoding properly

Monitoring and Debugging​

Logging Issues​

Issue: Missing log entries​

Solution:

  • Check log level configuration
  • Verify log destination settings
  • Ensure proper permissions

Issue: Log format problems​

Solution:

  • Configure structured logging
  • Use consistent timestamp formats
  • Include relevant context data

Debugging Techniques​

  1. Use Debug Nodes: Insert debug nodes to inspect data flow
  2. Enable Verbose Logging: Increase log verbosity for troubleshooting
  3. Test Incrementally: Test workflows step by step
  4. Use Sample Data: Test with known good data first
  5. Check Node Documentation: Review specific node requirements

Getting Help​

Support Channels​

  • Community Forum: Discord
  • Documentation: Check node-specific documentation
  • GitHub Issues: Report bugs and feature requests
  • Support Email: contact@axonos.ai

Before Reporting Issues​

  1. Check this troubleshooting guide
  2. Review relevant documentation
  3. Test with minimal reproduction case
  4. Gather error logs and configuration
  5. Include system and version information

Information to Include​

  • Axon OS version
  • Node configuration
  • Error messages and stack traces
  • Sample input data (anonymized)
  • Expected vs actual behavior
  • Environment details

Best Practices for Prevention​

  1. Validate Inputs: Always validate data before processing
  2. Handle Errors: Implement proper error handling
  3. Test Thoroughly: Test workflows with various data scenarios
  4. Monitor Performance: Set up monitoring and alerts
  5. Keep Updated: Regularly update nodes and dependencies
  6. Document Changes: Maintain clear documentation
  7. Use Version Control: Track workflow changes
  8. Regular Backups: Backup important workflows and data