> ## Documentation Index
> Fetch the complete documentation index at: https://helix-digitalocean.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common issues and error messages in Helix CLI v2

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:
   ```bash theme={null}
   echo 'export PATH="$HOME/.helix/bin:$PATH"' >> ~/.bashrc
   source ~/.bashrc
   ```

2. For Zsh users:
   ```bash theme={null}
   echo 'export PATH="$HOME/.helix/bin:$PATH"' >> ~/.zshrc
   source ~/.zshrc
   ```

3. Verify installation:
   ```bash theme={null}
   ls -la ~/.helix/bin/helix
   ```

### Permission denied during installation

**Problem**: Installation fails with permission errors.

**Solution**: Use system-wide installation with sudo:

```bash theme={null}
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:
   ```bash theme={null}
   helix init
   ```

2. Navigate to project directory:
   ```bash theme={null}
   cd /path/to/your/project
   ```

3. Check for `helix.toml`:
   ```bash theme={null}
   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:

```toml theme={null}
# 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:
   ```bash theme={null}
   helix status
   ```

2. Add the missing instance:
   ```bash theme={null}
   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:
   ```bash theme={null}
   sudo systemctl start docker
   ```

3. Check Docker status:
   ```bash theme={null}
   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:

```bash theme={null}
sudo usermod -aG docker $USER
newgrp docker
```

### Port already in use

**Error:**

```
bind: address already in use
```

**Solutions:**

1. Find process using the port:
   ```bash theme={null}
   lsof -i :6969
   ```

2. Stop conflicting service or use different port:
   ```toml theme={null}
   [local.dev]
   port = 7070
   ```

### Container name conflict

**Error:**

```
Container name "/helix_my-app_dev" is already in use
```

**Solution**: Remove old container:

```bash theme={null}
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:**

```bash theme={null}
helix auth login
```

### Expired credentials

**Error:**

```
Authentication token expired
```

**Solution**: Re-authenticate:

```bash theme={null}
helix auth logout
helix auth login
```

### Fly.io authentication issues

**Error:**

```
Error authenticating with Fly.io
```

**Solutions:**

1. For CLI auth:
   ```bash theme={null}
   flyctl auth login
   ```

### AWS ECR authentication failed

**Error:**

```
no basic auth credentials
```

**Solutions:**

1. Configure AWS CLI:
   ```bash theme={null}
   aws configure
   ```

2. Login to ECR:
   ```bash theme={null}
   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:

```bash theme={null}
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:
   ```bash theme={null}
   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:
   ```bash theme={null}
   docker ps -a | grep helix
   ```

2. View container logs:
   ```bash theme={null}
   docker logs helix_my-app_dev
   ```

3. Test connection:
   ```bash theme={null}
   curl http://localhost:6969/health
   ```

4. Check port binding:
   ```bash theme={null}
   docker port helix_my-app_dev
   ```

## Migration Issues

### v1 project detected

**Error:**

```
Found v1 project configuration. Run 'helix migrate' to upgrade to v2.
```

**Solution:**

```bash theme={null}
helix migrate --dry-run  # Preview changes
helix migrate            # Execute migration
```

### Migration backup failed

**Error:**

```
Failed to create backup directory
```

**Solution**: Create backup manually:

```bash theme={null}
cp -r . ../project-backup
helix migrate --no-backup
```

## Performance Issues

### Slow build times

**Solutions:**

1. Use release mode for production only:
   ```toml theme={null}
   [local.dev]
   build_mode = "debug"  # Faster builds
   ```

2. Reduce vector config for development:
   ```toml theme={null}
   [local.dev.vector_config]
   m = 8                 # Lower for dev
   ef_construction = 64  # Lower for dev
   ```

3. Clean Docker cache:
   ```bash theme={null}
   docker system prune -a
   ```

### High memory usage

**Solutions:**

1. Limit database size:
   ```toml theme={null}
   [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:
   ```bash theme={null}
   docker logs helix_my-app_dev --tail 100
   ```

2. Inspect exit code:
   ```bash theme={null}
   docker inspect helix_my-app_dev --format='{{.State.ExitCode}}'
   ```

3. Increase memory limits:
   ```toml theme={null}
   [local.dev.limits]
   max_memory_gb = 8
   ```

## Network Issues

### Cannot connect to instance

**Debugging steps:**

1. Check if container is running:
   ```bash theme={null}
   docker ps | grep helix
   ```

2. Test localhost connection:
   ```bash theme={null}
   telnet localhost 6969
   ```

3. Check firewall settings:
   ```bash theme={null}
   # macOS
   sudo pfctl -s rules

   # Linux
   sudo iptables -L
   ```

### Connection refused

**Solutions:**

1. Verify port configuration:
   ```bash theme={null}
   grep port helix.toml
   ```

2. Check port forwarding:
   ```bash theme={null}
   docker inspect helix_my-app_dev | grep -A 10 "Ports"
   ```

3. Try different port:
   ```toml theme={null}
   [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:

```bash theme={null}
# 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](https://docs.helix-db.com)

2. **Search GitHub issues**: [https://github.com/HelixDB/helix-db/issues](https://github.com/HelixDB/helix-db/issues)

3. **Join Discord**: [https://discord.gg/2stgMPr5BD](https://discord.gg/2stgMPr5BD)

4. **Contact support**: [founders@helix-db.com](mailto: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

<Accordion title="Before reporting an issue, try these steps">
  * [ ] 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`
</Accordion>