Installation Issues

This guide helps resolve common problems during Planar installation and setup.

Julia Installation Issues

Julia Version Compatibility

Problem: Planar requires Julia 1.11 or later.

Solution:

# Check your Julia version
julia --version

# If version is too old, install Julia 1.11+
# Visit https://julialang.org/downloads/

Package Installation Failures

Problem: Pkg.instantiate() fails with dependency errors.

Solution:

# Clear package cache and retry
using Pkg
Pkg.gc()
Pkg.resolve()
Pkg.instantiate()

Environment Setup Issues

Directory Permissions

Problem: Permission denied when creating user directory.

Solution:

# Ensure proper permissions
chmod 755 user/
mkdir -p user/logs user/keys

Environment Variables

Problem: JULIA_PROJECT not set correctly.

Solution:

# Set project environment
export JULIA_PROJECT=Planar
# or for interactive features
export JULIA_PROJECT=PlanarInteractive

Configuration Issues

Missing Configuration Files

Problem: user/planar.toml not found.

Solution:

# Copy example configuration
cp examples/planar.toml user/planar.toml
# Edit with your settings

API Key Configuration

Problem: Exchange API authentication fails.

Solution:

Create user/secrets.toml:

[exchanges.binance]
api_key = "your_api_key"
secret = "your_secret_key"
sandbox = true  # for testing

Verify API key permissions on exchange
Test connectivity in paper mode first

Dependency Issues

Python Integration Problems

Problem: PythonCall.jl fails to initialize.

Solution:

CCXT Installation Issues

Problem: Ccxt.jl fails to load.

Solution:

# Reinstall CCXT
import Pkg

try
    # Remove and reinstall CCXT
    Pkg.rm("Ccxt")
    Pkg.add("Ccxt")
    
    println("CCXT package reinstalled successfully")
    
    # Test the installation
    using Ccxt
    println("CCXT loaded successfully")
    
catch e
    @warn "CCXT installation issue: $e"
    println("Try manual installation or check network connection")
end

Docker Issues

Container Build Failures

Problem: Docker build fails with compilation errors.

Solution:

# Clean build with no cache
docker build --no-cache -t planar .

# Or use pre-built image
docker pull docker.io/bubbleparticles/planar-sysimage

Volume Mount Issues

Problem: User directory not accessible in container.

Solution:

# Ensure proper volume mounting
docker run -v $(pwd)/user:/app/user planar

Performance Issues

Slow Compilation

Problem: First run takes very long to compile.

Solution:

Use sysimage for faster startup
Enable precompilation: JULIA_PRECOMP=1
Consider using Docker image with pre-compiled sysimage

Memory Issues

Problem: Out of memory during large backtests.

Solution:

Reduce data range or timeframe
Use progressive data loading
Increase system memory or use swap

Network Issues

Firewall Issues

Problem: Exchange API calls blocked by firewall.

Solution:

Whitelist exchange API endpoints
Use VPN if necessary
Test with curl to verify connectivity

Getting Additional Help

If these solutions don't resolve your issue:

Check the main troubleshooting guide
Review exchange-specific issues
Search GitHub Issues
Create a new issue with detailed error information