Troubleshooting Overview

This page provides quick access to troubleshooting resources. For detailed solutions, visit the specific troubleshooting guides in the troubleshooting section.

Quick Access to Solutions

Most Common Issues

Installation Problems → Installation Issues
Strategy Not Working → Strategy Problems
Slow Performance → Performance Issues
Exchange Errors → Exchange Issues

Emergency Quick Fixes

Complete Reset (Nuclear Option):

Dependency Issues:

Python Problems:

Comprehensive Troubleshooting Guides

For detailed solutions with step-by-step instructions, platform-specific guidance, and advanced diagnostics, see:

Troubleshooting Index - Complete troubleshooting guide with all categories
Installation Issues - Setup, dependencies, environment configuration
Strategy Problems - Development, execution, debugging
Performance Issues - Optimization, memory, speed
Exchange Issues - Connectivity, authentication, trading

This page previously contained comprehensive troubleshooting information. That content has been reorganized into categorized guides for better navigation and maintenance. If you're looking for specific troubleshooting information, please check the appropriate category above.

Quick Diagnostic Checklist

Before diving into specific issues, try these common solutions:

Environment Check: Ensure you're using the correct Julia project
```
julia --project=Planar  # or PlanarOptim
```
Dependency Resolution: Update and resolve all dependencies
Clean Restart: Exit Julia completely and restart with a fresh REPL
Check Environment Variables: Verify JULIA_PROJECT, JULIA_NUM_THREADS, and other relevant settings

Precompilation Issues

Dependency Conflicts

Symptoms: Precompilation fails after repository updates, package version conflicts

Diagnostic Steps:

Check for dependency conflicts in the output
Look for version incompatibilities in error messages
Verify all submodules are properly updated

REPL Startup Issues

Symptoms: Precompilation errors when activating project in existing REPL

Diagnostic Steps:

Check if Julia was started with correct project
Verify environment variables are set correctly
Look for conflicting package environments

Solutions:

# Preferred: Start Julia with project directly
julia --project=./Planar

# Alternative: For interactive features
julia --project=./PlanarOptim

# Check current project status
julia> using Pkg; Pkg.status()

Python-Dependent Precompilation

Symptoms: Segmentation faults during precompilation, Python-related errors

Diagnostic Steps:

Check if error occurs during Python module loading
Look for @py macro usage in precompilable code
Verify global cache states

Solutions:

Prevention:

Keep global constants empty during precompilation
Use lazy initialization for Python-dependent objects
Avoid @py macros in precompilable functions

Precompilation Failures

Symptoms: Package fails to load, precompilation hangs or errors, "breaks incremental compilation" warnings

Diagnostic Steps:

Check JULIA_PRECOMP environment variable — only packages listed here run precompile workloads
Look for common precompile pitfalls:
- @eval into Main — use $Pkg interpolation instead of using Pkg: Pkg
- __revise_mode__ = :eval in source code — remove from production files
- Live HTTP calls or gateway connections — wrap in try/catch
- External strategy module loading (strategy(:BareStrat)) — wrap in try/catch
Verify with --compiled-modules=no to bypass cached compilation

Solutions:

# Check environment variables
echo $JULIA_PRECOMP

# Test without cached precompilation
julia --project=Planar --compiled-modules=no -e "using Pkg; Pkg.status()"

# Force full precompilation
julia --project=Planar -e "using Pkg; Pkg.precompile()"

# Clear precompile cache and retry
rm -rf ~/.julia/compiled

Debug Symbol Issues

Symptoms: _debug_ not found errors during strategy execution

Diagnostic Steps:

Check if JULIA_DEBUG="all" is set
Verify module precompilation status
Look for debug/release mode mismatches

Python Integration Issues

Missing Python Dependencies

Symptoms: ModuleNotFoundError, missing Python packages, import failures

Diagnostic Steps:

Check if CondaPkg environment is properly initialized
Verify Python package installation status
Look for environment path issues

CondaPkg Environment Issues

Symptoms: Persistent Python module resolution failures, environment conflicts

Diagnostic Steps:

Check CondaPkg status and configuration
Verify environment variables are set correctly
Look for conflicting Python installations

Solutions:

Platform-Specific Notes:

Linux: Ensure system Python development headers are installed
macOS: May require Xcode command line tools
Windows: Verify PATH environment variable includes Python

Python-Julia Interop Issues

Symptoms: Type conversion errors, async operation failures, memory issues

Diagnostic Steps:

Check for type conversion problems between Python and Julia
Verify async operation compatibility
Look for memory management issues

Exchange Connection Issues

Unresponsive Exchange Instance

Symptoms: Timeout errors, connection refused, API calls hanging

Diagnostic Steps:

Check exchange status and maintenance schedules
Verify API credentials and permissions
Test network connectivity to exchange endpoints

Solutions:

Idle Connection Closure: If an exchange instance remains idle for an extended period, the connection may close. It should time out according to the ccxt exchange timeout. Following a timeout error, the connection will re-establish, and API-dependent functions will resume normal operation.

API Authentication Issues

Symptoms: Authentication errors, invalid API key messages, permission denied

Diagnostic Steps:

Verify API credentials in [secrets.toml](config.md#Secrets-Management)
Check API key permissions on exchange
Verify IP whitelist settings if applicable

Rate Limiting Issues

Symptoms: Rate limit exceeded errors, temporary bans, slow API responses

Diagnostic Steps:

Check current rate limit settings
Monitor API call frequency
Verify exchange-specific limits

Data Storage and Management Issues

LMDB Size Limitations

Symptoms: "MDBMAPFULL" errors, data saving failures, database write errors

Diagnostic Steps:

Check current database size usage
Monitor available disk space
Verify LMDB configuration

Solutions:

Prevention:

Monitor database growth regularly
Set initial size based on expected data volume
Implement automated size monitoring

Data Corruption Issues

Symptoms: Segfaults when saving OHLCV, corrupted data reads, database errors

Diagnostic Steps:

Check for incomplete write operations
Verify data integrity
Look for concurrent access issues

LMDB Platform Compatibility

Symptoms: "LMDB not available" errors, compilation failures

Diagnostic Steps:

Check if LMDB binary is available for your platform
Verify system dependencies
Look for compilation errors

Data Fetching and Pipeline Issues

Symptoms: Missing data, fetch timeouts, inconsistent data quality

Diagnostic Steps:

Check data source availability
Verify network connectivity
Monitor data quality metrics

Plotting and Visualization Issues

Misaligned Plotting Tooltips

Symptoms: Tooltips appear in wrong positions, rendering artifacts, display issues

Diagnostic Steps:

Check which Makie backend is currently active
Verify graphics driver compatibility
Test with different backends

Backend Installation and Configuration Issues

Symptoms: Backend not found, OpenGL errors, display server issues

Diagnostic Steps:

Check if required system libraries are installed
Verify display server configuration (Linux)
Test graphics driver compatibility

Solutions:

Platform-Specific Solutions:

Linux:

# Install required libraries
sudo apt-get install libgl1-mesa-glx libxrandr2 libxss1 libxcursor1 libxcomposite1 libasound2 libxi6 libxtst6

# For headless servers, use Xvfb
export DISPLAY=:99
Xvfb :99 -screen 0 1024x768x24 &

macOS:

# Install XQuartz if needed
brew install --cask xquartz

Windows:

Ensure graphics drivers are up to date
Try running Julia as administrator if permission issues occur

Plot Performance Issues

Symptoms: Slow rendering, memory issues with large datasets, unresponsive plots

Diagnostic Steps:

Check data size and complexity
Monitor memory usage during plotting
Verify backend performance characteristics

Interactive Features Not Working

Symptoms: Zoom/pan not responding, tooltips not appearing, selection not working

Diagnostic Steps:

Verify backend supports interactivity
Check if running in appropriate environment
Test with simple interactive examples

Strategy Development and Execution Issues

Strategy Loading and Compilation Issues

Symptoms: Strategy not found, compilation errors, module loading failures

Diagnostic Steps:

Check strategy file location and naming
Verify Project.toml configuration
Look for syntax errors in strategy code

Strategy Execution Errors

Symptoms: Runtime errors during strategy execution, unexpected behavior

Diagnostic Steps:

Check strategy logic and data dependencies
Verify market data availability
Look for timing or synchronization issues

Order Execution Issues

Symptoms: Orders not executing, incorrect order types, position management errors

Diagnostic Steps:

Check order parameters and validation
Verify exchange connectivity and permissions
Look for balance and margin issues

Development and Debugging Issues

VSCode Debugging Configuration

Symptoms: Breakpoints not triggering, debugging not working in strategy execution

Diagnostic Steps:

Check VSCode Julia extension configuration
Verify debugger settings for compiled modules
Test with simple debugging scenarios

Solutions:

/ In VSCode user settings.json
{
    "julia.debuggerDefaultCompiled": [
        "ALL_MODULES_EXCEPT_MAIN",
        "-Base.CoreLogging"
    ]
}

Performance Debugging

Symptoms: Slow strategy execution, high memory usage, CPU bottlenecks

Diagnostic Steps:

Profile strategy execution
Identify memory allocation hotspots
Check for inefficient data operations

Environment and Configuration Issues

Docker and Container Issues

Symptoms: Container startup failures, permission errors, volume mounting issues

Diagnostic Steps:

Check Docker installation and permissions
Verify volume mounts and file permissions
Test container networking

Solutions:

# Step 1: Test basic Docker functionality
docker run --rm hello-world

# Step 2: Check Planar container
docker run --rm -it bubbleparticles/planar-sysimage-optim julia --version

# Step 3: Fix permission issues (Linux)
sudo usermod -aG docker $USER
# Logout and login again

# Step 4: Mount user directory correctly
docker run -v $(pwd)/user:/app/user bubbleparticles/planar-sysimage-optim

Environment Variable Issues

Symptoms: Configuration not loading, unexpected behavior, missing settings

Diagnostic Steps:

Check environment variable values
Verify .envrc configuration
Test variable precedence

Solutions:

# Step 1: Check current environment
env | grep JULIA
env | grep PLANAR

# Step 2: Verify direnv configuration
cat .envrc
direnv allow

# Step 3: Test variable loading in Julia
julia -e 'println(ENV["JULIA_PROJECT"])'

Platform-Specific Issues

Linux-Specific Issues

Common Issues:

Missing system libraries for plotting backends
Permission issues with Docker
Display server configuration for headless systems

Solutions:

# Install required system packages
sudo apt-get update
sudo apt-get install build-essential libgl1-mesa-glx libxrandr2 libxss1

# For headless systems
export DISPLAY=:99
Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &

macOS-Specific Issues

Common Issues:

Xcode command line tools missing
Permission issues with system directories
Graphics driver compatibility

Solutions:

# Install Xcode command line tools
xcode-select --install

# Install required packages via Homebrew
brew install lmdb
brew install --cask xquartz

Windows-Specific Issues

Common Issues:

Path length limitations
PowerShell execution policy
Graphics driver issues

Solutions:

# Enable long paths
Set-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1

# Set execution policy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Update graphics drivers through Device Manager

Performance Troubleshooting

Strategy Execution Performance

Symptoms: Slow backtesting-mode), high CPU usage, long execution times

Diagnostic Steps:

Profile strategy execution to identify bottlenecks
Check data access patterns and frequency
Monitor memory allocation and garbage collection

Memory Usage Optimization

Symptoms: High memory usage, out-of-memory errors, slow garbage collection

Diagnostic Steps:

Monitor memory usage during execution
Identify memory leaks and excessive allocations
Check for large object retention

Symptoms: Slow data loading, high I/O wait times, database performance issues

Diagnostic Steps:

Monitor I/O operations and disk usage
Check data access patterns and caching
Verify database configuration and indexing

Optimization and Backtesting Performance

Symptoms: Slow parameter optimization, long backtesting times, inefficient search

Diagnostic Steps:

Profile optimization algorithms
Check parameter space size and search efficiency
Monitor parallel execution utilization

Parallel Processing and Threading

Symptoms: Poor multi-threading performance, race conditions, synchronization issues

Diagnostic Steps:

Check thread utilization and load balancing
Identify thread-safety issues
Monitor synchronization overhead

Plotting and Visualization Performance

Symptoms: Slow plot rendering, high memory usage during plotting, unresponsive plots

Diagnostic Steps:

Check data size and plot complexity
Monitor GPU/graphics memory usage
Test different backends for performance

Getting Help

Before Seeking Help

Check this troubleshooting guide for your specific issue
Search existing GitHub issues for similar problems
Try the diagnostic steps provided for your issue category
Gather relevant information:
- Julia version (julia --version)
- Planar version/commit
- Operating system and version
- Complete error messages and stack traces
- Minimal reproducible example

Where to Get Help

GitHub Issues: For bugs and feature requests
Discussions: For general questions and community support
Documentation: Check the comprehensive guides and API reference

Creating Effective Bug Reports

Include the following information:

Environment details: OS, Julia version, Planar version
Steps to reproduce: Minimal example that demonstrates the issue
Expected behavior: What you expected to happen
Actual behavior: What actually happened
Error messages: Complete error output and stack traces
Configuration: Relevant parts of your configuration files