This guide helps you resolve common issues when using the Helix CLI v2.

​
Installation Issues

​
Command not found: helix

Problem: After installation, helix command is not recognized. Solutions:
  1. Ensure PATH is updated: 
    echo 'export PATH="$HOME/.helix/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
  2. For Zsh users: 
    echo 'export PATH="$HOME/.helix/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
  3. Verify installation: 
    ls -la ~/.helix/bin/helix

​
Permission denied during installation

Problem: Installation fails with permission errors. Solution: Use system-wide installation with sudo: 
curl -fsSL https://raw.githubusercontent.com/HelixDB/helix-db/main/install.sh | sudo bash -- --system

​
Project Configuration Issues

​
Not in a Helix project directory

Error: 
Not in a Helix project directory. Run 'helix init' to create one.
Solutions:
  1. Initialize a new project: 
    helix init
  2. Navigate to project directory: 
    cd /path/to/your/project
  3. Check for helix.toml: 
    ls helix.toml

​
Invalid configuration in helix.toml

Error: 
Failed to parse helix.toml: invalid type: string "6969", expected u16
Solution: Ensure port numbers are integers without quotes: 
# Wrong
[local.dev]
port = "6969"

# Correct
[local.dev]
port = 6969

​
Instance not found

Error: 
Instance 'production' not found in configuration
Solutions:
  1. Check available instances: 
    helix status
  2. Add the missing instance: 
    helix add cloud --name production

​
Docker Issues

​
Docker daemon not running

Error: 
Cannot connect to Docker daemon. Is the Docker daemon running?
Solutions:
  1. Start Docker Desktop
  2. On Linux, start Docker service: 
    sudo systemctl start docker
  3. Check Docker status: 
    docker info

​
Permission denied for Docker socket

Error: 
permission denied while trying to connect to the Docker daemon socket
Solution: Add user to docker group: 
sudo usermod -aG docker $USER
newgrp docker

​
Port already in use

Error: 
bind: address already in use
Solutions:
  1. Find process using the port: 
    lsof -i :6969
  2. Stop conflicting service or use different port: 
    [local.dev]
port = 7070

​
Container name conflict

Error: 
Container name "/helix_my-app_dev" is already in use
Solution: Remove old container: 
docker rm helix_my-app_dev
# Or force remove
docker rm -f helix_my-app_dev

​
Authentication Issues

​
Helix Cloud authentication failed

Error: 
Credentials file not found. Please run 'helix auth login' first.
Solution: 
helix auth login

​
Expired credentials

Error: 
Authentication token expired
Solution: Re-authenticate: 
helix auth logout
helix auth login

​
Fly.io authentication issues

Error: 
Error authenticating with Fly.io
Solutions:
  1. For CLI auth: 
    flyctl auth login

​
AWS ECR authentication failed

Error: 
no basic auth credentials
Solutions:
  1. Configure AWS CLI: 
    aws configure
  2. Login to ECR: 
    aws ecr get-login-password --region us-west-2 | \
  docker login --username AWS --password-stdin \
  123456789.dkr.ecr.us-west-2.amazonaws.com

​
Build & Deployment Issues

​
Build fails with missing files

Error: 
Failed to copy queries: No such file or directory
Solution: Ensure queries directory exists: 
mkdir -p db
touch db/schema.hx db/queries.hx

​
Push fails for cloud instance

Error: 
Failed to upload to cloud: network timeout
Solutions:
  1. Check internet connection
  2. Verify authentication: 
    helix auth login
  3. Check cloud service status

​
Instance won’t start

Problem: helix push dev succeeds but instance isn’t accessible. Debugging steps:
  1. Check container status: 
    docker ps -a | grep helix
  2. View container logs: 
    docker logs helix_my-app_dev
  3. Test connection: 
    curl http://localhost:6969/health
  4. Check port binding: 
    docker port helix_my-app_dev

​
Migration Issues

​
v1 project detected

Error: 
Found v1 project configuration. Run 'helix migrate' to upgrade to v2.
Solution: 
helix migrate --dry-run  # Preview changes
helix migrate            # Execute migration

​
Migration backup failed

Error: 
Failed to create backup directory
Solution: Create backup manually: 
cp -r . ../project-backup
helix migrate --no-backup

​
Performance Issues

​
Slow build times

Solutions:
  1. Use release mode for production only: 
    [local.dev]
build_mode = "debug"  # Faster builds
  2. Reduce vector config for development: 
    [local.dev.vector_config]
m = 8                 # Lower for dev
ef_construction = 64  # Lower for dev
  3. Clean Docker cache: 
    docker system prune -a

​
High memory usage

Solutions:
  1. Limit database size: 
    [local.dev.vector_config]
db_max_size_gb = 5  # Reduce for local dev
  2. Adjust Docker resources in Docker Desktop settings

​
Container crashes

Debugging steps:
  1. Check logs: 
    docker logs helix_my-app_dev --tail 100
  2. Inspect exit code: 
    docker inspect helix_my-app_dev --format='{{.State.ExitCode}}'
  3. Increase memory limits: 
    [local.dev.limits]
max_memory_gb = 8

​
Network Issues

​
Cannot connect to instance

Debugging steps:
  1. Check if container is running: 
    docker ps | grep helix
  2. Test localhost connection: 
    telnet localhost 6969
  3. Check firewall settings: 
    # macOS
sudo pfctl -s rules

# Linux
sudo iptables -L

​
Connection refused

Solutions:
  1. Verify port configuration: 
    grep port helix.toml
  2. Check port forwarding: 
    docker inspect helix_my-app_dev | grep -A 10 "Ports"
  3. Try different port: 
    [local.dev]
port = 7070

​
Common Error Messages

​
”ENOENT: no such file or directory”

Cause: Missing required files Solution: Run helix init to create project structure

​
”EADDRINUSE: address already in use”

Cause: Port conflict Solution: Use different port or stop conflicting service

​
”EPERM: operation not permitted”

Cause: Permission issue Solution: Check file permissions or run with appropriate privileges

​
”ECONNREFUSED: Connection refused”

Cause: Service not running Solution: Start the instance with helix push <instance>

​
”ETIMEDOUT: operation timed out”

Cause: Network or performance issue Solution: Check network connection and increase timeout settings

​
Debug Mode

Enable debug logging for detailed troubleshooting: 
# Set log level
export HELIX_LOG_LEVEL=debug

# Run command with debug output
HELIX_LOG_LEVEL=debug helix push dev

# View detailed Docker logs
docker logs helix_my-app_dev -f --tail 100

​
Getting Help

If you’re still experiencing issues:
  1. Check the documentation: https://docs.helix-db.com
  2. Search GitHub issues: https://github.com/HelixDB/helix-db/issues
  3. Join Discord: https://discord.gg/2stgMPr5BD
  4. Contact support: founders@helix-db.com
When reporting issues, include:
  • Helix CLI version (helix --version)
  • Operating system and version
  • Docker version (docker --version)
  • Error messages and logs
  • Steps to reproduce the issue
  • helix.toml configuration (remove sensitive data)

​
Quick Fixes Checklist

  • Update CLI: helix update
  • Validate configuration: helix check
  • Restart Docker Desktop
  • Clean up resources: helix prune
  • Check disk space: df -h
  • Verify network connectivity
  • Review recent changes to .hx files
  • Check file permissions
  • Try with a fresh project: helix init in a new directory
  • Enable debug logging: HELIX_LOG_LEVEL=debug