Troubleshooting

Common issues and their solutions.

Installation Issues

“command not found: hi-shell”

Problem: hi-shell is not in your PATH.

Solution:

If installed via the quick install script, restart your terminal
If installed via cargo, ensure ~/.cargo/bin is in your PATH:
```
export PATH="$HOME/.cargo/bin:$PATH"
```
If built from source, copy the binary to a PATH directory:
```
cp target/release/hi-shell /usr/local/bin/
```

Build Fails from Source

Problem: Compilation errors when building with cargo build.

Solutions:

Ensure you have Rust 1.70+: rustc --version
Update Rust: rustup update
For Metal acceleration on macOS, ensure Xcode Command Line Tools are installed:
```
xcode-select --install
```
For CUDA on Linux, ensure the CUDA toolkit is installed

Connection Issues

“Connection refused” (Local Providers)

Problem: Cannot connect to Ollama or LM Studio.

Solutions:

Ollama:

# Check if Ollama is running
ollama list

# Start Ollama if not running
ollama serve

# Test the API directly
curl http://localhost:11434/api/tags

LM Studio:

Open LM Studio
Go to the Local Server tab
Ensure a model is loaded and server is started
Verify the port matches your config (default: 1234)

“Invalid API key” (Cloud Providers)

Problem: API key is rejected.

Solutions:

Verify the key in the provider’s dashboard
Check for extra whitespace or newlines
Ensure the key hasn’t been revoked
Try regenerating the key

For OpenRouter: Key starts with sk-or- For Anthropic: Key starts with sk-ant- For OpenAI: Key starts with sk-

Network Timeout

Problem: Request times out.

Solutions:

Check your internet connection
Try a different model (smaller models respond faster)
For local providers, ensure the model is fully loaded before sending requests
Increase timeout if on a slow connection

Model Issues

Embedded Model Download Fails

Problem: Cannot download the embedded model.

Solutions:

Check your internet connection
Ensure enough disk space (models are 700MB-3GB)
Try a different model
Manually download from Hugging Face and place in cache directory

Model Returns Nonsensical Commands

Problem: Generated commands don’t make sense.

Solutions:

Use a larger/better model (e.g., switch from embedded to Ollama with a 7B model)
Be more specific in your natural language description
Try a cloud provider for the best quality

Embedded Model Is Slow

Problem: Long response times with embedded models.

Solutions:

Build with hardware acceleration:

# macOS
cargo build --release --features metal
# Linux with NVIDIA GPU
cargo build --release --features cuda

Use a smaller model (e.g., 1B parameter instead of 3B)
Close other resource-intensive applications

REPL Issues

REPL Crashes or Freezes

Problem: The interactive REPL stops responding.

Solutions:

Press Ctrl+C to cancel the current operation
Press Ctrl+D to exit the REPL
Restart hi-shell
Run with verbose logging: hi-shell -v

History Not Working

Problem: Command history isn’t persisted between sessions.

Solution: This is expected — REPL history is session-based. Each new session starts fresh.

Configuration Issues

Config File Not Found

Problem: hi-shell can’t find or create the config file.

Solutions:

Ensure the config directory exists:

# Linux/macOS
mkdir -p ~/.config/hi-shell

Check directory permissions
Run hi-shell --init to create a fresh config

Config Changes Not Taking Effect

Problem: Modified config doesn’t seem to work.

Solutions:

Restart hi-shell (config is read at startup)
Check for TOML syntax errors in the config file
Validate the config:
```
cat ~/.config/hi-shell/config.toml
```

Getting More Help

If your issue isn’t listed here:

Check the FAQ
Search existing GitHub Issues
Open a new issue with:
- Your OS and hi-shell version
- Your provider and model
- The error message
- Steps to reproduce