Troubleshooting¶

This guide covers common issues you may encounter when using clinvoker, along with diagnostic methods and solutions. Issues are organized by category for easy reference.

Diagnostic Methods¶

Before diving into specific issues, here are general diagnostic approaches:

Collect Execution Details¶

# Show resolved backend command without executing
clinvk --dry-run "your prompt"

# Capture structured output for inspection
clinvk --output-format json "your prompt"

Check System Status¶

# View version and build info
clinvk version

# Check available backends
clinvk config show

# Quick health check on recent sessions
clinvk sessions list --limit 5

Dry Run Mode¶

See what command would be executed without actually running it:

clinvk --dry-run "your prompt"

Backend Not Available¶

Symptoms¶

Error: Backend 'claude' not found in PATH
Error: No backends available
Exit code: 126

Causes¶

Backend CLI not installed
Backend CLI not in PATH
Backend CLI has incorrect permissions
Backend CLI is a different version than expected

Solutions¶

1. Verify Installation¶

# Check if backend CLIs are installed
which claude codex gemini

# Check versions
claude --version
codex --version
gemini --version

2. Add to PATH¶

# Add to shell profile (~/.bashrc, ~/.zshrc, etc.)
export PATH="$PATH:/usr/local/bin"

# Reload profile
source ~/.bashrc  # or ~/.zshrc

3. Check Permissions¶

# Verify executable permissions
ls -la $(which claude)

# Fix if needed
chmod +x /path/to/claude

4. Verify clinvk Detection¶

# Check which backends clinvk can find
clinvk config show | grep -A2 "available"

Session Issues¶

Session Corruption¶

Symptoms: - Error: Failed to load session: invalid JSON - Session file appears empty or truncated - Cannot resume a previously working session

Causes: 1. Process killed during session write 2. Disk full during write 3. Concurrent modification without proper locking

Solutions:

# Check session file integrity
ls -la ~/.clinvk/sessions/

# View session content (JSON should be valid)
cat ~/.clinvk/sessions/<session-id>.json | python -m json.tool

# If corrupted, remove the session
clinvk sessions delete <session-id>

# Or clean all sessions
rm -rf ~/.clinvk/sessions/*

Session Locking Issues¶

Symptoms: - Error: Failed to acquire store lock: timeout - Operations hang indefinitely - "Resource temporarily unavailable" errors

Causes: 1. Another clinvk process holding the lock 2. Previous process crashed without releasing lock 3. Stale lock file

Solutions:

# Check for running clinvk processes
ps aux | grep clinvk

# Kill stale processes if necessary
kill -9 <pid>

# Remove stale lock file (use with caution)
rm -f ~/.clinvk/.store.lock

# Verify lock file permissions
ls -la ~/.clinvk/

Session Not Found¶

Symptoms: - Error: Session 'abc123' not found - Cannot resume previous session

Solutions:

# List all available sessions
clinvk sessions list

# Check session directory
ls -la ~/.clinvk/sessions/

# Search for session by partial ID
find ~/.clinvk/sessions/ -name "*abc*"

API Server Problems¶

Server Startup Issues¶

Symptoms: - Error: Address already in use - Error: Permission denied when binding to port - Server exits immediately

Solutions:

Port Already in Use:

# Find process using the port
lsof -i :8080
# or
netstat -tlnp | grep 8080

# Use a different port
clinvk serve --port 3000

# Or kill the existing process
kill -9 <pid>

Permission Denied (Low Ports):

# Use port > 1024 (no root required)
clinvk serve --port 8080

# Or run with sudo (not recommended)
sudo clinvk serve --port 80

Authentication Issues¶

Symptoms: - Error: Unauthorized (401) - Error: Invalid API key

Solutions:

# Check if API keys are configured
clinvk config show | grep api_keys

# Verify API key in request
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:8080/api/v1/health

# Check environment variable
echo $CLINVK_API_KEY

# Test without authentication (if no keys configured)
curl http://localhost:8080/health

Rate Limiting Issues¶

Symptoms: - Error: Rate limit exceeded (429) - Requests being rejected after certain volume

Solutions:

# Check rate limit configuration
clinvk config show | grep rate_limit

# Adjust rate limits in config
clinvk config set server.rate_limit_rps 100

# For parallel execution, reduce concurrency
clinvk parallel --max-parallel 2 --file tasks.json

Performance Issues¶

Slow Response Times¶

Symptoms: - Commands take longer than expected - Timeouts occurring

Causes: 1. Backend rate limiting 2. Large context/prompt size 3. Network latency to backend APIs 4. Insufficient system resources

Solutions:

# Check backend status
curl http://localhost:8080/api/v1/backends

# Monitor system resources
top
iostat -x 1

# Increase timeout
clinvk config set timeout 300

# Use faster model (model names passed directly to backend CLI)
clinvk -b claude -m haiku "prompt"
clinvk -b gemini -m gemini-2.5-flash "prompt"

High Memory Usage¶

Symptoms: - clinvk process using excessive memory - System becoming unresponsive

Solutions:

# Check memory usage
ps aux | grep clinvk

# Limit parallel execution
clinvk parallel --max-parallel 2 --file tasks.json

# Clean old sessions
clinvk sessions clean --older-than 7d

# Use ephemeral mode (no session storage)
clinvk --ephemeral "prompt"

Disk Space Issues¶

Symptoms: - Error: No space left on device - Session operations failing

Solutions:

# Check disk space
df -h

# Check session storage size
du -sh ~/.clinvk/sessions/

# Clean old sessions
clinvk sessions clean --older-than 30d

# Or manually clean
rm -rf ~/.clinvk/sessions/*.json

Configuration Issues¶

Config File Not Loading¶

Symptoms: - Settings not applied - Default values being used

Solutions:

# Check config file location
ls -la ~/.clinvk/config.yaml

# Validate YAML syntax
cat ~/.clinvk/config.yaml | python -c "import yaml,sys; yaml.safe_load(sys.stdin)"

# Check file permissions
chmod 600 ~/.clinvk/config.yaml

# View effective configuration
clinvk config show

# Check for environment variable overrides
echo $CLINVK_BACKEND
echo $CLINVK_CLAUDE_MODEL
echo $CLINVK_CODEX_MODEL

Environment Variables Not Applied¶

Symptoms: - Environment settings ignored - CLI flags work but env vars don't

Solutions:

# Verify variable is exported
export CLINVK_BACKEND=codex

# Check current shell variables
env | grep CLINVK

# Remember priority: CLI flags > Environment > Config file

Platform-Specific Issues¶

macOS¶

Gatekeeper Blocking:

# Remove quarantine attribute
xattr -d com.apple.quarantine /path/to/clinvk

# Or allow in System Preferences > Security & Privacy

Notarization Issues:

# If downloaded binary won't run
sudo spctl --master-disable  # Temporarily disable (use with caution)
# Then re-enable after first run
sudo spctl --master-enable

Windows¶

PATH Issues:

# Add to PATH via PowerShell
$env:Path += ";C:\path\to\clinvk"

# Or permanently via System Properties
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";C:\path\to\clinvk", "User")

Antivirus False Positives:

Some antivirus software may flag clinvk. Add an exclusion if necessary.

Linux¶

Permission Denied:

chmod +x /path/to/clinvk

SELinux Issues:

# Check SELinux status
getenforce

# If enforcing, check for denials
ausearch -m avc -ts recent

# Create policy module if needed
audit2allow -a -M clinvk
semodule -i clinvk.pp

Diagnostic Workflow¶

Increase Logging Signal¶

# Inspect the exact command that would run
clinvk --dry-run "prompt"

# Use JSON output to inspect response payloads
clinvk --output-format json "prompt"

# Start server with explicit bind settings
clinvk serve --host 127.0.0.1 --port 8080

Log Locations¶

CLI Mode: - Logs go to stderr by default - Redirect to file: clinvk "prompt" 2> debug.log

Server Mode: - Logs to stdout/stderr - Use systemd/journald for persistent logs: journalctl -u clinvk - Or redirect: clinvk serve > server.log 2>&1

Common Log Patterns¶

Backend Command:

[DEBUG] Executing: claude --print --model sonnet "prompt"
[DEBUG] Working directory: /home/user/project
[DEBUG] Exit code: 0

Session Operations:

[DEBUG] Loading session: abc123
[DEBUG] Acquiring file lock
[DEBUG] Session saved successfully

API Requests:

[DEBUG] POST /api/v1/prompt
[DEBUG] Request body: {...}
[DEBUG] Response: 200 OK

Getting Help¶

If issues persist after trying the above solutions:

Check Documentation
FAQ
Guides
Reference
Search Issues
GitHub Issues
Use search with error message
Open a New Issue Include:
clinvk version (clinvk version)
Operating system and version
Backend versions (claude --version, etc.)
Complete error message
Steps to reproduce
Debug logs (if possible)
Community Support
Start a GitHub Discussion
Check existing discussions for similar problems

FAQ - Frequently asked questions
Design Decisions - Architecture explanations
Contributing - Development setup

Troubleshooting¶

Diagnostic Methods¶

Collect Execution Details¶

Check System Status¶

Dry Run Mode¶

Backend Not Available¶

Symptoms¶

Causes¶

Solutions¶

1. Verify Installation¶

2. Add to PATH¶

3. Check Permissions¶

4. Verify clinvk Detection¶

Session Issues¶

Session Corruption¶

Session Locking Issues¶

Session Not Found¶

API Server Problems¶

Server Startup Issues¶

Authentication Issues¶

Rate Limiting Issues¶

Performance Issues¶

Slow Response Times¶

High Memory Usage¶

Disk Space Issues¶

Configuration Issues¶

Config File Not Loading¶

Environment Variables Not Applied¶

Platform-Specific Issues¶

macOS¶

Windows¶

Linux¶

Diagnostic Workflow¶

Increase Logging Signal¶

Log Locations¶

Common Log Patterns¶

Getting Help¶

Related Documentation¶