Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt

Use this file to discover all available pages before exploring further.

For the complete documentation index optimized for AI agents, see llms.txt.
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 = "dev"  # 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

​
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