Troubleshooting Guide

Common issues and solutions when working with Reflow.

Installation Issues

Rust Compilation Errors

Problem: Build fails with compiler errors

error[E0432]: unresolved import `reflow_network::Graph`

Solution:

Ensure you have the latest Rust version (1.85+)
Update dependencies: cargo update
Clean build cache: cargo clean && cargo build

Problem: Missing system dependencies

error: linking with `cc` failed: exit status: 1

Solution:

Linux: Install build essentials: sudo apt-get install build-essential
macOS: Install Xcode command line tools: xcode-select --install
Windows: Install Visual Studio Build Tools

WebAssembly Build Issues

Problem: wasm-pack fails to build

Error: failed to execute `wasm-pack build`: No such file or directory

Solution:

Install wasm-pack: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
Add wasm target: rustup target add wasm32-unknown-unknown
Verify installation: wasm-pack --version

Runtime Issues

Actor Initialization Failures

Problem: Actors fail to start

Error: Actor 'data_processor' failed to initialize: E001

Solutions:

Check actor configuration:

// Verify all required ports are defined
fn get_input_ports(&self) -> Vec<PortDefinition> {
    vec![
        PortDefinition::new("input", PortType::Any),
    ]
}

Validate actor state:

// Ensure actor is in valid initial state
impl Actor for MyActor {
    fn process(&mut self, inputs: HashMap<String, Message>) -> Result<HashMap<String, Message>, ActorError> {
        if !self.initialized {
            return Err(ActorError::NotInitialized);
        }
        // ... processing logic
    }
}

Check dependencies:

// Verify all dependencies are available
impl MyActor {
    pub fn new() -> Result<Self, ActorError> {
        let dependency = SomeDependency::connect()
            .map_err(|_| ActorError::DependencyUnavailable)?;
        
        Ok(Self { dependency, initialized: true })
    }
}

Message Routing Errors

Problem: Messages not reaching destination actors

Warning: Message dropped - no route to 'processor.input'

Solutions:

Verify connections:

// Check connection exists
network.connect("source", "output", "processor", "input").await?;

// Verify actor and port names
let actors = network.list_actors();
println!("Available actors: {:?}", actors);

Check port compatibility:

// Ensure port types match
source_actor.get_output_ports(); // Returns Vec<PortDefinition>
processor_actor.get_input_ports(); // Should have compatible types

Monitor message flow:

network.enable_message_tracing(true);
// Check logs for message routing information

Memory Issues

Problem: Out of memory errors

Error: Memory allocation failed: E005

Solutions:

Configure memory limits:

[memory]
max_heap_size = "2GB"
gc_frequency = 50
enable_memory_pooling = true

Implement proper cleanup:

impl Drop for MyActor {
    fn drop(&mut self) {
        // Clean up resources
        self.cleanup_connections();
        self.release_buffers();
    }
}

Use memory profiling:

use memory_stats::memory_stats;

if let Some(usage) = memory_stats() {
    println!("Memory usage: {} bytes", usage.physical_mem);
}

Network Issues

Connection Timeouts

Problem: Network operations timeout

Error: Connection timeout after 5000ms: E003

Solutions:

Increase timeout values:

[network]
timeout_ms = 30000  # Increase to 30 seconds

Implement retry logic:

use reflow_components::utility::RetryActor;

let retry_actor = RetryActor::new()
    .max_attempts(3)
    .backoff_strategy(BackoffStrategy::Exponential)
    .base_delay(Duration::from_millis(100));

Check network connectivity:

# Test connectivity
curl -I http://your-endpoint
ping your-server

WebSocket Connection Issues

Problem: WebSocket connections fail

Error: WebSocket connection failed: Connection refused

Solutions:

Verify server configuration:

[websocket]
enable = true
port = 8080
bind_address = "0.0.0.0"

Check firewall settings:

# Linux
sudo ufw allow 8080

# macOS
sudo pfctl -f /etc/pf.conf

Test WebSocket endpoint:

// Test in browser console
const ws = new WebSocket('ws://localhost:8080');
ws.onopen = () => console.log('Connected');
ws.onerror = (error) => console.error('Error:', error);

Script Runtime Issues

Deno Permission Errors

Problem: Deno scripts fail due to permissions

Error: Requires read access to "./data", run again with --allow-read

Solutions:

Configure permissions:

[scripts.deno]
allow_read = true
allow_net = false
allow_write = false

Specify allowed paths:

let config = ScriptConfig {
    runtime: ScriptRuntime::JavaScript,
    permissions: ScriptPermissions {
        allow_read: Some(vec!["./data".to_string(), "./config".to_string()]),
        allow_net: Some(vec!["api.example.com".to_string()]),
        allow_write: None,
    },
    ..Default::default()
};

Python Import Errors

Problem: Python modules not found

ModuleNotFoundError: No module named 'requests'

Solutions:

Install dependencies:
```
pip install -r requirements.txt
```

Configure virtual environment:

[scripts.python]
virtual_env = "./venv"
requirements = "requirements.txt"

Verify Python path:
```
import sys
print(sys.path)
```

WebAssembly Module Loading

Problem: WASM modules fail to load

Error: Invalid WASM module format

Solutions:

Verify WASM file:
```
wasm-objdump -h module.wasm
```

Check module exports:

wasm-objdump -x module.wasm | grep Export

Validate memory configuration:

[scripts.wasm]
max_memory = "64MB"
stack_size = "1MB"

Graph Issues

Cycle Detection Errors

Problem: Graph contains cycles

Error: Cycle detected in graph: node1 -> node2 -> node3 -> node1

Solutions:

Analyze graph structure:

let analysis = graph.analyze_structure();
if analysis.has_cycles {
    println!("Cycles found: {:?}", analysis.cycles);
}

Remove problematic connections:

// Remove cycle-causing connection
graph.remove_connection("node3", "output", "node1", "input")?;

Implement cycle breaking:

let cycles = graph.detect_cycles();
for cycle in cycles {
    // Break cycle by removing weakest connection
    let weakest_connection = find_weakest_connection(&cycle);
    graph.remove_connection_by_id(&weakest_connection.id)?;
}

Port Type Mismatches

Problem: Incompatible port types

Error: Port type mismatch: Cannot connect String output to Integer input

Solutions:

Add type conversion:

use reflow_components::data_operations::ConverterActor;

let converter = ConverterActor::new()
    .add_conversion(PortType::String, PortType::Integer, |value| {
        if let Message::String(s) = value {
            s.parse::<i64>().map(Message::Integer).ok()
        } else {
            None
        }
    });

Use flexible port types:

PortDefinition::new("input", PortType::Any)

Implement custom validation:

fn validate_connection(&self, output_type: &PortType, input_type: &PortType) -> bool {
    match (output_type, input_type) {
        (PortType::String, PortType::Integer) => true, // Allow with conversion
        (PortType::Any, _) => true,
        (_, PortType::Any) => true,
        (a, b) => a == b,
    }
}

Performance Issues

High CPU Usage

Problem: Actors consuming excessive CPU

Warning: Actor 'data_processor' CPU usage: 95%

Solutions:

Profile actor performance:

use std::time::Instant;

impl Actor for MyActor {
    fn process(&mut self, inputs: HashMap<String, Message>) -> Result<HashMap<String, Message>, ActorError> {
        let start = Instant::now();
        
        // ... processing logic
        
        let duration = start.elapsed();
        if duration.as_millis() > 100 {
            log::warn!("Slow processing: {:?}", duration);
        }
        
        Ok(result)
    }
}

Implement batching:

use reflow_components::synchronization::BatchActor;

let batcher = BatchActor::new()
    .batch_size(100)
    .timeout(Duration::from_millis(50));

Use async processing:

async fn process_async(&mut self, inputs: HashMap<String, Message>) -> Result<HashMap<String, Message>, ActorError> {
    // Use tokio::task::yield_now() to yield control
    tokio::task::yield_now().await;
    
    // CPU-intensive work
    let result = heavy_computation(inputs).await;
    
    Ok(result)
}

Memory Leaks

Problem: Memory usage continuously increases

Warning: Memory usage increased to 2.1GB (threshold: 2GB)

Solutions:

Monitor memory allocation:

use reflow_network::profiling::MemoryProfiler;

let profiler = MemoryProfiler::new();
profiler.start_monitoring();

// ... run workflows

let report = profiler.generate_report();
println!("Memory hotspots: {:?}", report.hotspots);

Implement proper cleanup:

impl Actor for MyActor {
    fn process(&mut self, inputs: HashMap<String, Message>) -> Result<HashMap<String, Message>, ActorError> {
        // Process inputs
        let result = self.do_processing(inputs)?;
        
        // Clean up temporary data
        self.cleanup_temp_data();
        
        Ok(result)
    }
}

Use memory limits:

let config = ActorConfig {
    memory_limit: Some(100 * 1024 * 1024), // 100MB limit
    ..Default::default()
};

Debugging Tips

Enable Debug Logging

[logging]
level = "debug"
targets = [
    "reflow_network=debug",
    "reflow_components=info",
    "my_app=trace"
]

Use Network Introspection

// Enable network monitoring
network.enable_monitoring(true);

// Get network statistics
let stats = network.get_statistics();
println!("Messages processed: {}", stats.total_messages);
println!("Average latency: {:?}", stats.average_latency);

// List active actors
let actors = network.list_active_actors();
for (id, status) in actors {
    println!("Actor {}: {:?}", id, status);
}

Actor State Inspection

// Enable actor introspection
actor.enable_introspection(true);

// Get actor state
let state = actor.get_internal_state();
println!("Actor state: {:?}", state);

// Monitor port activity
let port_stats = actor.get_port_statistics();
for (port, stats) in port_stats {
    println!("Port {}: {} messages", port, stats.message_count);
}

Graph Visualization

// Export graph for visualization
let dot_format = graph.export_dot();
std::fs::write("graph.dot", dot_format)?;

// Generate SVG visualization
// Use graphviz: dot -Tsvg graph.dot -o graph.svg

Common Error Patterns

Error E001: Actor Initialization Failed

Check actor dependencies
Verify configuration parameters
Ensure required resources are available

Error E002: Message Routing Error

Verify connection exists
Check port names and types
Ensure target actor is running

Error E003: Network Connection Failed

Check network connectivity
Verify server endpoints
Review firewall settings

Error G002: Cycle Detected

Analyze graph structure
Remove cycle-causing connections
Consider using async patterns

Error C004: Port Compatibility Error

Check port type definitions
Add type conversion actors
Use flexible port types

Getting Help

Check logs: Enable debug logging for detailed information
Use monitoring tools: Enable network and actor monitoring
Review configuration: Verify all configuration parameters
Test in isolation: Create minimal test cases
Community support: Open issues on GitHub with detailed error information

Diagnostic Tools

Health Check Endpoint

// Add health check to your application
use warp::Filter;

let health = warp::path("health")
    .map(|| {
        let status = check_system_health();
        warp::reply::json(&status)
    });

warp::serve(health)
    .run(([127, 0, 0, 1], 8080))
    .await;

Metrics Collection

use prometheus::{Counter, Histogram, register_counter, register_histogram};

let message_counter = register_counter!("reflow_messages_total", "Total messages processed").unwrap();
let processing_time = register_histogram!("reflow_processing_duration_seconds", "Processing time").unwrap();

// In actor processing
message_counter.inc();
let _timer = processing_time.start_timer();

Performance Profiling

# CPU profiling
cargo install flamegraph
cargo flamegraph --bin reflow-app

# Memory profiling  
cargo install heaptrack
heaptrack target/release/reflow-app

For additional help, see:

API Reference - Complete API documentation
Architecture Overview - System architecture
Performance Optimization - Optimization techniques

Uh oh!

FilesExpand file tree

troubleshooting-guide.md

Latest commit

History

troubleshooting-guide.md

File metadata and controls

Troubleshooting Guide

Installation Issues

Rust Compilation Errors

WebAssembly Build Issues

Runtime Issues

Actor Initialization Failures

Message Routing Errors

Memory Issues

Network Issues

Connection Timeouts

WebSocket Connection Issues

Script Runtime Issues

Deno Permission Errors

Python Import Errors

WebAssembly Module Loading

Graph Issues

Cycle Detection Errors

Port Type Mismatches

Performance Issues

High CPU Usage

Memory Leaks

Debugging Tips

Enable Debug Logging

Use Network Introspection

Actor State Inspection

Graph Visualization

Common Error Patterns

Error E001: Actor Initialization Failed

Error E002: Message Routing Error

Error E003: Network Connection Failed

Error G002: Cycle Detected

Error C004: Port Compatibility Error

Getting Help

Diagnostic Tools

Health Check Endpoint

Metrics Collection

Performance Profiling