Troubleshooting

This guide helps you diagnose and resolve common issues you might encounter when working with BoCoFlow.

Startup Issues

Application Won't Start

Symptoms:

• BoCoFlow doesn't launch after clicking the icon
• The application window flashes briefly then closes

Possible Solutions:

1. Check system requirements:

   • Ensure your system meets the minimum requirements
   • Verify you have enough disk space

2. Reinstall the application:

   • Uninstall BoCoFlow completely
   • Download a fresh copy of the installer
   • Install with administrator privileges

3. Check logs:

   • Navigate to the application logs directory:
     • Windows: %APPDATA%\BoCoFlow\logs
     • macOS: ~/Library/Application Support/BoCoFlow/logs
     • Linux: ~/.local/share/BoCoFlow/logs
   • Look for error messages in the most recent log file

Backend Server Error

Symptoms:

• Application starts but shows "Backend server error"
• Workflows can't be loaded or executed

Possible Solutions:

1. Check backend logs:

   • Click "View Backend Logs" from the application menu
   • Look for specific error messages

2. Port conflict:

   • Check if another application is using port 8000
   • Close other applications that might be using this port

3. Reset application state:

   • Close BoCoFlow
   • Delete the session store:
     • Windows: %APPDATA%\BoCoFlow\session_store.db
     • macOS: ~/Library/Application Support/BoCoFlow/session_store.db
     • Linux: ~/.local/share/BoCoFlow/session_store.db
   • Restart BoCoFlow

Workflow Setup Issues

Working Directory Problems

Symptoms:

• "Working directory not set" error
• File not found errors despite correct paths

Possible Solutions:

1. Set working directory properly:

   • Click "Setup" in the toolbar
   • Set an absolute path to a directory with write permissions

2. Check path format:

   • Ensure paths use the correct format (forward slashes, proper prefixes)
   • Use rel: for paths relative to working directory
   • Use abs: for absolute paths

3. Check permissions:

   • Ensure the application has read/write permissions for the working directory
   • Try creating a test file in the directory manually to verify

Custom Nodes Directory Issues

Symptoms:

• Custom nodes don't appear in the node menu
• Errors when trying to use custom nodes

Possible Solutions:

1. Check directory structure:

   • Ensure your custom nodes follow the required structure
   • Python files should be in appropriate category subdirectories

2. Reload nodes:

   • After adding custom nodes, click "Setup" then "OK" to reload nodes
   • Check if custom nodes appear in the node menu

3. Check for Python errors:

   • View backend logs for Python errors in your custom node code
   • Fix any syntax or import errors in your custom node files

Node Execution Issues

Node Fails to Execute

Symptoms:

• Node shows "Failed" status after execution
• Error appears in log panel

Possible Solutions:

1. Check node configuration:

   • Verify all required fields are filled correctly
   • Check file paths exist and are accessible

2. Check input data:

   • Ensure preceding nodes executed successfully
   • Verify the data format meets the node's expectations

3. View detailed error:

   • Check the log panel for specific error messages
   • Click on the failed node to see status details

Workflow Freezes During Execution

Symptoms:

• Application becomes unresponsive during workflow execution
• Execution progress indicator runs indefinitely

Possible Solutions:

1. Check for infinite loops:

   • Ensure your workflow doesn't contain circular dependencies
   • Check custom node code for potential infinite loops

2. Monitor system resources:

   • Check if the system is running out of memory
   • Break large workflows into smaller parts

3. Restart the application:

   • Force quit the application
   • Restart and try executing nodes individually rather than the entire workflow

Data and File Issues

File Not Found Errors

Symptoms:

• "File not found" error during node execution
• Nodes fail despite correct path configuration

Possible Solutions:

1. Check path format and prefixes:

   • Use rel: for paths relative to working directory
   • Use abs: for absolute paths
   • Verify path separators (use forward slashes /)

2. Verify file existence:

   • Check if the file exists at the specified location
   • Ensure file names and extensions are correct

3. Check working directory:

   • Confirm your working directory is set correctly
   • Try using absolute paths instead of relative paths

Data Format Issues

Symptoms:

• "Invalid data format" or similar errors
• Unexpected results in visualization nodes

Possible Solutions:

1. Check input data format:

   • View the output of preceding nodes
   • Ensure data structure matches what the node expects

2. Use manipulation nodes:

   • Add data transformation nodes to convert between formats
   • Use TableViewNode to inspect data at various stages

3. Check node documentation:

   • Review the node's expected input format
   • Configure the node appropriately for your data

Conda and Environment Issues

Conda Integration Problems

Symptoms:

• Errors related to Python packages or environments
• "Conda environment not found" errors

Possible Solutions:

1. Verify Conda installation:

   • Check that Conda is installed and in your PATH
   • Try running conda --version in a terminal

2. Check environment configuration:

   • Ensure the specified Conda environment exists
   • Verify it contains all required packages

3. Try without Conda:

   • Temporarily disconnect Conda integration
   • See if the issue persists with the default environment

Missing Package Errors

Symptoms:

• "Import Error" or "Module not found" in logs
• Nodes fail with package-related errors

Possible Solutions:

1. Install required packages:

   • Install missing packages in your Conda environment
   • Use conda install <package> or pip install <package>

2. Check package compatibility:

   • Ensure package versions are compatible
   • Try updating or downgrading specific packages

3. Create a dedicated environment:

   • Create a new Conda environment specifically for BoCoFlow
   • Install all required packages in this environment

UI and Canvas Issues

Canvas Display Problems

Symptoms:

• Nodes not rendering correctly
• Connections appear broken or misaligned

Possible Solutions:

1. Reset the view:

   • Click the "Reset View" button in the canvas controls
   • Try zooming in and out

2. Clear browser cache:

   • Clear application cache:
     • Windows: Press Ctrl+Shift+Delete
     • macOS: Press Command+Shift+Delete
   • Restart the application

3. Recreate problematic nodes:

   • Delete and recreate nodes that display incorrectly
   • Save your workflow frequently to avoid data loss

Slow Performance

Symptoms:

• UI becomes laggy or unresponsive
• Dragging nodes is slow or jerky

Possible Solutions:

1. Simplify complex workflows:

   • Break large workflows into multiple smaller workflows
   • Use saved intermediate results between workflows

2. Reduce canvas elements:

   • Delete unnecessary nodes and connections
   • Save completed sections of your workflow and start fresh

3. Check system resources:

   • Close other resource-intensive applications
   • Monitor CPU and memory usage

Saving and Loading Issues

Cannot Save Workflow

Symptoms:

• Error when trying to save workflow
• Saved file is corrupt or empty

Possible Solutions:

1. Check write permissions:

   • Ensure you have write access to the target directory
   • Try saving to a different location

2. Check disk space:

   • Verify you have sufficient disk space
   • Clean up unnecessary files if needed

3. Use working directory:

   • Save to a location within your working directory
   • Use a simple file name without special characters

Cannot Load Workflow

Symptoms:

• Error when trying to load a workflow file
• Workflow loads but is missing nodes or connections

Possible Solutions:

1. Check file format:

   • Ensure the file is a valid BoCoFlow workflow file
   • Verify the file isn't corrupted

2. Set correct working directory:

   • Set the working directory to match the original workflow
   • Or update paths in the workflow to match the new working directory

3. Check for missing custom nodes:

   • Ensure any custom nodes used in the workflow are available
   • Configure the custom nodes directory correctly

Getting Additional Help

If you continue to experience issues after trying these troubleshooting steps:

1. Check the documentation:

   • Review relevant sections of the BoCoFlow documentation
   • Look for specific guidance on your issue

2. Search for known issues:

   • Check the BoCoFlow GitHub repository for reported issues
   • See if your problem has already been solved

3. Contact support:

   • Provide detailed information about your problem
   • Include logs, screenshots, and steps to reproduce the issue
   • Describe your system configuration and BoCoFlow version