Skip to main content

​
Troubleshooting

Common issues you might encounter and how to fix them. If you don’t find your issue here, check the console output for specific error messages.

​
Code Generation Issues

Symptoms: Clicking Generate shows errors or fails completely.Possible Causes & Solutions:
  1. Schema validation errors
    • Check schemas panel for red error indicators
    • Fix schema syntax errors
    • Ensure all referenced schemas exist
    • Verify no circular schema references
  2. Node code errors
    • Check that all nodes have code written
    • Verify code syntax is correct for the language
    • Look for type mismatches in node code
    • Check console for specific error messages
  3. Connection errors
    • Verify all connections are valid
    • Check that port types match
    • Ensure no orphaned connections
  4. Project structure issues
    • Verify project directory structure is correct
    • Check file permissions
    • Ensure all required directories exist
Symptoms: Code generation succeeds but generated code has compilation errors.Solutions:
  • Check schema definitions for invalid types
  • Verify node code doesn’t use unsupported features
  • Review generated code for syntax issues
  • Check language-specific requirements (Rust version, Python version, etc.)
  • Try cleaning and regenerating: delete generated files and regenerate

​
Build Issues

Symptoms: Code generation succeeds but build fails.Possible Causes & Solutions:
  1. Missing dependencies
    • Install required build tools (Rust, Python, C++ compiler)
    • Check that dependencies are in PATH
    • Verify language versions meet requirements
  2. Compilation errors
    • Check node code for syntax errors
    • Verify schema types are compatible with target language
    • Review build output for specific error messages
    • Check for missing imports or includes
  3. Linker errors
    • Verify all required libraries are installed
    • Check library paths are correct
    • Ensure transport libraries (iceoryx2, zenoh) are available
  4. Platform-specific issues
    • Check platform requirements
    • Verify system libraries are installed
    • Review platform-specific build instructions
Symptoms: Build takes a very long time.Solutions:
  • First build is always slower (dependencies download)
  • Use release builds for faster runtime (but slower build)
  • Check system resources (CPU, memory, disk)
  • Consider incremental builds (only rebuild changed nodes)
  • Clean build cache if corrupted: cargo clean (for Rust)

​
Runtime Issues

Symptoms: Clicking Run does nothing or shows errors.Possible Causes & Solutions:
  1. Build not completed
    • Ensure build completed successfully
    • Check for build errors in console
    • Try rebuilding the project
  2. Missing dependencies
    • Verify runtime dependencies are available
    • Check that transport libraries are installed
    • Ensure Python interpreter is available (for Python nodes)
  3. Port conflicts
    • Check for port conflicts (if using network transport)
    • Verify no other instances are running
    • Check firewall settings
  4. Configuration errors
    • Review runtime configuration
    • Check environment variables
    • Verify project settings
Symptoms: Graph runs but produces no output.Possible Causes & Solutions:
  1. Publisher not sending
    • Check publisher node code
    • Verify publisher is actually executing
    • Check for errors in publisher code
    • Ensure publisher has output port configured
  2. Connections incorrect
    • Verify connections are correct
    • Check that topics are created
    • Ensure port types match
  3. Trigger configuration
    • Check trigger settings on input ports
    • Verify nodes are configured to execute
    • Ensure at least one input is a trigger
  4. Subscriber not receiving
    • Check subscriber node code
    • Verify subscriber is executing
    • Look for errors in subscriber code
    • Check console for error messages
Symptoms: Graph starts but crashes or becomes unresponsive.Possible Causes & Solutions:
  1. Infinite loops
    • Check node code for infinite loops
    • Verify trigger configuration
    • Look for circular dependencies
  2. Memory issues
    • Check for memory leaks in node code
    • Verify data structures aren’t growing unbounded
    • Review buffer sizes
  3. Deadlocks
    • Check for blocking operations
    • Verify nodes aren’t waiting for each other
    • Review synchronization logic
  4. Exceptions/panics
    • Check console for error messages
    • Review node code for exception handling
    • Verify data validation

​
Connection Issues

Symptoms: Editor won’t let you create connections.Solutions:
  • Check that port types match exactly
  • Verify both nodes are in the same graph
  • Ensure ports aren’t already connected
  • Check for schema validation errors
  • Verify connection mode is active (C key)
Symptoms: Connections are gone after saving or moving nodes.Solutions:
  • Verify both nodes still exist
  • Check that graph file was saved correctly
  • Look for validation errors
  • Try recreating the connection
  • Check for project corruption
Symptoms: Can’t connect because types don’t match.Solutions:
  • Verify both ports use the same schema
  • Check that schemas are correctly defined
  • Ensure schema files are saved and loaded
  • Look for schema validation errors
  • Try refreshing the project

​
Schema Issues

Symptoms: Error saying schema doesn’t exist.Solutions:
  • Verify schema file exists in schemas/ directory
  • Check schema name matches exactly (case-sensitive)
  • Ensure schema file is valid YAML
  • Reload project to refresh schema cache
  • Check for typos in schema name
Symptoms: Schema shows red error indicator.Solutions:
  • Check YAML syntax (indentation, colons, etc.)
  • Verify field types are valid
  • Ensure no circular references
  • Check that referenced schemas exist
  • Review schema structure
Symptoms: Created schema but can’t use it.Solutions:
  • Verify schema was saved
  • Check for validation errors
  • Try refreshing the project
  • Ensure you’re in the same project
  • Check schema file is in correct location

​
Performance Issues

Symptoms: Graph executes but is slow.Solutions:
  • Profile to identify bottlenecks
  • Check node code for inefficient operations
  • Verify data structures are appropriate
  • Consider using Rust for performance-critical nodes
  • Review transport settings (local vs network)
  • Check system resources
Symptoms: Graph uses too much memory.Solutions:
  • Check for memory leaks in node code
  • Verify buffers aren’t growing unbounded
  • Review data structure sizes
  • Consider using more efficient data types
  • Check for unnecessary data copying

​
Getting Help

If you can’t resolve an issue:
  1. Check console output - Error messages often provide clues
  2. Review logs - Check log files for detailed error information
  3. Search documentation - Look for similar issues in guides
  4. Check examples - Compare with working examples
  5. Simplify - Create a minimal reproduction case

​
Diagnostic Commands

Use these to gather information:
  • Check version: cerulion-graph-editor --version
  • Check dependencies: Verify Rust, Python, C++ are installed
  • Validate project: Check for project structure issues
  • Review logs: Check console and log files

​
Next Steps

Reference

Review glossary for term definitions.

How-to Guides

Learn proper workflow to avoid issues.

Examples

Compare with working examples.

Core Troubleshooting

Check Cerulion Core troubleshooting for framework issues.