Troubleshooting Guide

This guide helps you diagnose and fix common issues with Rust TUI Coder.

Installation Issues
Configuration Problems
API Connection Issues
Tool Execution Errors
UI/Display Problems
Performance Issues
Platform-Specific Issues

Installation Issues

Error: "Package not found"

Problem: cargo install rust_tui_coder fails

Solutions:

Update Rust
```
rustup update stable
```

Check Rust version

rustc --version  # Should be 1.70 or higher

Clear cargo cache

rm -rf ~/.cargo/registry/index/*
cargo install rust_tui_coder

Error: "Failed to compile"

Problem: Build fails during installation

Solutions:

Check system dependencies

# Ubuntu/Debian
sudo apt-get install build-essential pkg-config libssl-dev

# macOS
xcode-select --install

# Fedora
sudo dnf install gcc openssl-devel

Use specific version

cargo install rust_tui_coder --version 1.0.0

Build from source

git clone https://github.com/yourusername/rust_tui_coder.git
cd rust_tui_coder
cargo build --release
./target/release/rct

Configuration Problems

Error: "Config file not found"

Problem: Application can't find config.toml

Diagnostic:

# Check current directory
pwd

# List files
ls -la | grep config

Solutions:

Create config file

cat > config.toml << EOF
[llm]
api_key = "your-api-key"
api_base_url = "https://api.openai.com/v1"
model_name = "gpt-4"
EOF

Use example config

cp config_example.toml config.toml
# Edit with your details
nano config.toml

Check file location
- Config must be in the directory where you run the app
- Or use environment variables instead

Error: "Invalid TOML format"

Problem: Config file has syntax errors

Diagnostic:

# Validate TOML
cat config.toml

Common Issues:

Missing quotes

# Wrong
api_key = sk-abc123

# Correct
api_key = "sk-abc123"

Wrong section headers
```
# Wrong
[LLM]

# Correct
[llm]
```

Extra characters

# Wrong
api_key = "key",

# Correct
api_key = "key"

Solution:

# Minimal valid config
[llm]
api_key = "your-key-here"
api_base_url = "https://api.openai.com/v1"
model_name = "gpt-4"

Error: "Missing required field"

Problem: Config is missing a required field

Solution: Ensure all required fields are present:

[llm]
api_key = "required"
api_base_url = "required"
model_name = "required"
provider = "optional"

API Connection Issues

Error: "Invalid API key"

Problem: API authentication fails

Diagnostic:

# Check API key format
cat config.toml | grep api_key

Solutions:

OpenAI keys
- Should start with sk-
- Get from: https://platform.openai.com/api-keys
- Check for extra spaces or newlines
Anthropic keys
- Should start with sk-ant-
- Get from: https://console.anthropic.com/

Verify key is active

# Test OpenAI key
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

Error: "Connection refused" or "Connection timeout"

Problem: Can't connect to API server

Diagnostic:

# Test connectivity
ping api.openai.com

# Test API endpoint
curl -I https://api.openai.com/v1/models

Solutions:

Check internet connection
```
ping google.com
```
Check firewall
- Ensure port 443 (HTTPS) is open
- Check corporate firewall/proxy

Verify API base URL

# OpenAI
api_base_url = "https://api.openai.com/v1"

# Anthropic
api_base_url = "https://api.anthropic.com"

# Local (Ollama)
api_base_url = "http://localhost:11434/v1"

Use proxy (if needed)

export HTTPS_PROXY=http://proxy.company.com:8080
rct

Error: "Rate limit exceeded"

Problem: Too many API requests

Solutions:

Wait and retry
- OpenAI: Wait 60 seconds
- Anthropic: Check your rate limits
Check your usage
- OpenAI: https://platform.openai.com/usage
- Anthropic: https://console.anthropic.com/

Use slower model

model_name = "gpt-3.5-turbo"  # Instead of gpt-4

Error: "Model not found"

Problem: Specified model doesn't exist or you don't have access

Solutions:

Check model name spelling

# Correct
model_name = "gpt-4"

# Wrong
model_name = "gpt4"
model_name = "gpt-4-turbo"  # Use correct model ID

Verify model access
- GPT-4: Requires paid OpenAI account
- Claude: Check Anthropic access

Use available model

# OpenAI (always available)
model_name = "gpt-3.5-turbo"

# Anthropic
model_name = "claude-3-opus-20240229"

Tool Execution Errors

Error: "Permission denied" (File operations)

Problem: Can't read/write files

Diagnostic:

# Check file permissions
ls -la filename

# Check directory permissions
ls -la .

Solutions:

Check ownership

# Make file writable
chmod 644 filename

# Make directory writable
chmod 755 directory

Run with correct user

# Don't run as root unnecessarily
whoami

Check file locks
- Close other programs using the file
- Check for .lock files

Error: "Command not found" (Code execution)

Problem: Required interpreter not installed

Diagnostic:

# Check if installed
python3 --version
node --version
ruby --version

Solutions:

Install missing interpreter

# Python
sudo apt-get install python3  # Ubuntu
brew install python3          # macOS

# Node.js
sudo apt-get install nodejs
brew install node

# Ruby
sudo apt-get install ruby
brew install ruby

Check PATH
```
echo $PATH
which python3
```

Error: "No such file or directory"

Problem: Tool can't find specified file

Diagnostic:

# Check if file exists
ls -la path/to/file

# Check current directory
pwd

Solutions:

Use correct path
- Relative paths: src/main.rs
- Absolute paths: /home/user/project/src/main.rs
Create missing directories
```
mkdir -p path/to/directory
```
Check working directory
- App runs in the directory where you launched it
- Use /stats to see current context

UI/Display Problems

Problem: Garbled text or escape sequences

Symptoms:

Strange characters: ^[[0m
Colors don't work
Box drawing characters broken

Solutions:

Set TERM variable
```
export TERM=xterm-256color
rct
```
Use compatible terminal
- Good: iTerm2, GNOME Terminal, Alacritty, Windows Terminal
- Poor: Basic terminals, old terminal emulators

Check terminal capabilities

echo $TERM
tput colors  # Should show 256

Problem: UI doesn't update / frozen screen

Solutions:

Restart application
- Press Ctrl+C to quit
- Launch again

Check terminal size

# Terminal should be at least 80x24
tput cols  # Should be >= 80
tput lines # Should be >= 24

Resize terminal window
- Make it larger
- Restart app after resizing

Problem: Can't see cursor or input

Solutions:

Check input area
- Scroll to bottom with End key
- Input area is at the very bottom
Clear screen
- Restart the application
- Check if other programs are interfering

Problem: Scrolling doesn't work

Solutions:

Use correct keys
- Up / Down: Line by line
- PgUp / PgDn: Page by page
- Home / End: Top / Bottom
Check if conversation has content
- No scrolling if conversation is short
Focus on correct area
- Scrolling affects conversation area only

Performance Issues

Problem: Slow response times

Diagnostic:

Check usage with /stats
Note: First request is always slower (cold start)

Solutions:

Check model

# Faster
model_name = "gpt-3.5-turbo"

# Slower but better
model_name = "gpt-4"

Check network

# Test latency
ping api.openai.com

# Test speed
curl -w "@curl-format.txt" -o /dev/null -s https://api.openai.com/v1/models

Use local model

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Run a model
ollama run codellama

# Configure
[llm]
api_base_url = "http://localhost:11434/v1"
model_name = "codellama"

Problem: High memory usage

Diagnostic:

# Check memory
top | grep rct

Solutions:

Restart application periodically
- Long conversations use more memory
- Quit and restart to clear
Limit conversation length
- Keep interactions focused
- Start new sessions for new tasks

Problem: Application crashes

Diagnostic:

Check error message
Look for panic messages

Solutions:

Update to latest version
```
cargo install rust_tui_coder --force
```

Check logs

# Run with backtrace
RUST_BACKTRACE=1 rct

Report bug
- Create GitHub issue with:
  - Error message
  - Steps to reproduce
  - System information

Platform-Specific Issues

Linux Issues

Problem: "Cannot open shared object file"

Solution:

# Install missing libraries
sudo apt-get install libssl-dev pkg-config

Problem: Terminal colors don't work

Solution:

# Install 256-color support
sudo apt-get install ncurses-term
export TERM=xterm-256color

macOS Issues

Problem: "xcrun: error: invalid active developer path"

Solution:

xcode-select --install

Problem: OpenSSL linking errors

Solution:

brew install openssl
export OPENSSL_DIR=$(brew --prefix openssl)
cargo build --release

Windows Issues

Problem: PowerShell execution policy

Solution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problem: ANSI colors not working

Solution:

Use Windows Terminal (not cmd.exe)

Enable ANSI colors:

Set-ItemProperty HKCU:\Console VirtualTerminalLevel -Type DWORD 1

Problem: Git commands don't work

Solution:

Install Git for Windows
Ensure git.exe is in PATH

Advanced Diagnostics

Enable Debug Logging

# Run with verbose output
RUST_LOG=debug rct

# Or with backtrace
RUST_BACKTRACE=full rct

Test API Connection Manually

# OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

# Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-opus-20240229",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Verify Installation

# Check installed version
cargo install --list | grep rust_tui_coder

# Verify binary
which rct
rct --version  # If version flag is implemented

Getting Help

If you're still experiencing issues:

Check documentation
- README.md - General information
- GETTING_STARTED.md - Setup guide
- API.md - API reference
Search existing issues
- Check GitHub issues for similar problems
- See if solution already exists
Create an issue
- Provide detailed information:
  - Operating system and version
  - Rust version (rustc --version)
  - Application version
  - Configuration (remove API key!)
  - Complete error message
  - Steps to reproduce
- Use the bug report template
Community help
- Join discussions on GitHub
- Ask in community forums

Common Pitfalls

Pitfall 1: Wrong working directory

Problem: Files aren't where you expect

Solution: Application runs in the directory where you launch it

cd /path/to/your/project
rct

Pitfall 2: API key in config has extra characters

Problem: Copy-paste added spaces or newlines

Solution: Check carefully

# Wrong - has space at end
api_key = "sk-abc123 "

# Correct
api_key = "sk-abc123"

Pitfall 3: Expecting instant results with GPT-4

Problem: GPT-4 can take 10-30 seconds to respond

Solution: This is normal! GPT-4 is slower but more capable

Pitfall 4: Not using quotes in TOML

Problem: String values without quotes

Solution: Always quote strings in TOML

model_name = "gpt-4"  # Not: model_name = gpt-4

Still need help? Open an issue on GitHub with detailed information!

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

Troubleshooting Guide

Table of Contents

Installation Issues

Error: "Package not found"

Error: "Failed to compile"

Configuration Problems

Error: "Config file not found"

Error: "Invalid TOML format"

Error: "Missing required field"

API Connection Issues

Error: "Invalid API key"

Error: "Connection refused" or "Connection timeout"

Error: "Rate limit exceeded"

Error: "Model not found"

Tool Execution Errors

Error: "Permission denied" (File operations)

Error: "Command not found" (Code execution)

Error: "No such file or directory"

UI/Display Problems

Problem: Garbled text or escape sequences

Problem: UI doesn't update / frozen screen

Problem: Can't see cursor or input

Problem: Scrolling doesn't work

Performance Issues

Problem: Slow response times

Problem: High memory usage

Problem: Application crashes

Platform-Specific Issues

Linux Issues

macOS Issues

Windows Issues

Advanced Diagnostics

Enable Debug Logging

Test API Connection Manually

Verify Installation

Getting Help

Common Pitfalls

Pitfall 1: Wrong working directory

Pitfall 2: API key in config has extra characters

Pitfall 3: Expecting instant results with GPT-4

Pitfall 4: Not using quotes in TOML