Skip to main content
Repr not working? Something feels off? Let’s debug it. This guide covers the most common issues and how to fix them. Start with the health check, then jump to your specific problem.

​
The Universal Fix: Run Doctor

When something’s wrong, start here: 
repr doctor
Output: 
Checking repr health...

✓ Config: valid (v3)
✓ Stories: 45 files, no corruption detected
✓ Local LLM: Ollama (llama3.2) - connected
✓ Git: 2.40.0 - found
✓ Tracked repos: 5 repositories
⚠ Repo warning: 1 missing (/old/path/deleted-repo)

Recommendations:
  1. Remove missing repo: repr repos remove /old/path/deleted-repo
  
Overall health: Good (1 warning)
This catches 80% of issues. If there’s a problem, repr doctor tells you how to fix it. Still broken? Read on.

​
Common Issues

​
”Local LLM not found”

Symptoms: 
Error: Cannot connect to local LLM
Tried: http://localhost:11434/v1
Connection refused
Causes:
  • Ollama (or your local LLM) isn’t running
  • Wrong endpoint configured
Fix:
1

Check if Ollama is running

# Try to reach Ollama
curl http://localhost:11434/api/tags
If you get “connection refused”, Ollama isn’t running.
2

Start Ollama

# macOS/Linux
ollama serve

# Or if installed via Homebrew, it should auto-start
brew services start ollama
3

Pull a model if you haven't

ollama pull llama3.2
4

Test the connection

repr llm test
Should show:
✓ Local LLM: Connected
✓ Model: llama3.2
✓ Response time: 234ms
Still broken? Maybe your LLM is on a different port: 
# Check what's running
lsof -i :11434

# If it's on a different port, configure repr
repr config set llm.local_api_url http://localhost:YOUR_PORT/v1
repr llm test

​
“Not authenticated” / “Auth token expired”

Symptoms: 
Error: Not authenticated
Run 'repr login' to sign in
Or: 
Error: Auth token expired
Please login again
Fix: 
repr login
This opens your browser for re-authentication. Once you sign in, you’re good. Don’t want to use cloud? If you’re getting auth errors but want local-only mode: 
repr privacy lock-local
Now repr won’t try to authenticate. It’ll only use local features.

​
”Repository not tracked”

Symptoms: 
Error: Repository ~/code/my-project not tracked
Run 'repr repos add ~/code/my-project' to track it
Fix: 
# Add the repo
repr repos add ~/code/my-project

# Or add multiple at once
repr repos add ~/code/project-1 ~/code/project-2

# Or re-scan your code directory
repr init ~/code
Check what’s tracked: 
repr repos list
Output: 
Tracked Repositories:

✓ ~/code/my-project (active, 143 commits)
✓ ~/code/frontend-app (active, 87 commits)
⚠ ~/code/old-project (missing - directory not found)

Total: 3 tracked (2 active, 1 missing)
Remove repos you don’t want: 
repr repos remove ~/code/old-project

​
“Git hook not working” / “Commits not being queued”

Symptoms: You’ve installed hooks, but when you commit, nothing happens. repr hooks status shows hooks aren’t firing. Diagnose: 
repr hooks status
Output: 
Hook Status:

~/code/my-project:
  post-commit: ✗ Not installed
  
~/code/frontend-app:
  post-commit: ✓ Installed
  Last triggered: Never
Fix:
1

Reinstall hooks

repr hooks install --all
This re-installs hooks in all tracked repos.
2

Check for conflicting hooks

Some repos have existing hooks that might conflict:
ls -la ~/code/my-project/.git/hooks/
If you see post-commit.old or post-commit.sample, there was a pre-existing hook.Repr tries to be smart and chain hooks, but occasionally this fails. Manually check .git/hooks/post-commit and make sure it includes the repr hook.
3

Test manually

Make a commit and check if it queued:
cd ~/code/my-project
git commit --allow-empty -m "Test hook"

# Check if it was queued
repr hooks status
Look for “Last triggered” to update.
Still not working? The hook might be erroring silently. Check the hook script: 
cat ~/code/my-project/.git/hooks/post-commit
You should see something like: 
#!/bin/sh
repr hooks post-commit "$PWD" "$1" || true
If that’s missing, reinstall: 
repr hooks install --repo ~/code/my-project

​
“Corrupted config”

Symptoms: 
Error: Config file corrupted or invalid
Location: ~/.repr/config.json
Fix:
1

Back up your config (just in case)

cp ~/.repr/config.json ~/.repr/config.json.backup
2

Try to view the config

cat ~/.repr/config.json
If it’s valid JSON, you can manually fix it. If it’s completely broken, reset it:
3

Reset config to defaults

repr config reset
This creates a fresh config file. You’ll need to reconfigure:
repr init ~/code
repr llm configure
Restore specific settings: If you have a backup, you can merge settings: 
# Edit config manually
repr config edit
This opens ~/.repr/config.json in your $EDITOR. Copy settings from your backup.

​
”Out of disk space” / “Slow performance”

Symptoms: Repr is slow or you’re running out of disk space. Check storage: 
repr data
Output: 
Local Data Storage

Stories: 2.1 MB
Profiles: 340 KB
Cache: 1.2 GB  ← Might be large
Config: 8 KB
Total: 1.5 GB
Fix: 
# Clear cache (keeps stories and config)
repr data clear-cache
This can free up significant space. Repr caches LLM responses and intermediate data. Clearing the cache won’t delete your stories. Still slow? Your local LLM might be underpowered: 
repr llm test
If response time is >5 seconds, consider:
  • Using a smaller model: ollama pull phi3 (lighter than llama3.2)
  • Using cloud LLM: repr generate --cloud (requires login)
  • Using BYOK: repr llm add openai (your own API key)

​
“Sync conflicts” / “Can’t push to cloud”

Symptoms: 
Error: Sync conflict detected
Story 01ABC... edited on multiple devices

Or:

Error: Push failed
Server returned 409 Conflict
Diagnose: 
repr status
Shows: 
Sync status:
  ⚠ 1 conflict to resolve
  ↓ 2 remote stories newer than local
  ↑ 3 local stories not on remote
Fix:
1

Force pull (use remote version)

repr pull --force
This overwrites your local changes with the remote version. Your local edits are backed up to ~/.repr/conflicts/.
2

Or force push (use local version)

repr push --force
This overwrites the remote with your local version.
3

Or manually resolve

Check the conflict directory:
ls ~/.repr/conflicts/
cat ~/.repr/conflicts/01ABC....json
Pick the version you want and manually restore it:
cp ~/.repr/conflicts/01ABC....json ~/.repr/stories/
Prevent conflicts: Always sync before working: 
repr pull  # Start of session
# ... do work ...
repr push  # End of session

​
“Stories not generating” / “LLM errors”

Symptoms: 
Error: Failed to generate stories
LLM returned error: 500 Internal Server Error

Or:

Generating stories...
[Long pause, then timeout]
Diagnose: 
# Test your LLM connection
repr llm test
Common causes:
  1. Local LLM crashed: Restart Ollama 
    pkill ollama
ollama serve
  2. Model not loaded: Pull the model again 
    ollama pull llama3.2
  3. Out of memory: Your model is too big for your RAM 
    # Try a smaller model
ollama pull phi3
repr config set llm.local_model phi3
  4. API rate limit (BYOK): You hit your provider’s rate limit 
    Error: Rate limit exceeded
    Wait a few minutes or switch providers: 
    repr llm use byok:anthropic

​
“Can’t find repr command” / “Command not found”

Symptoms: 
$ repr
-bash: repr: command not found
Fix:
1

Check if repr is installed

which repr
If nothing shows up, repr isn’t in your PATH.
2

If installed via Homebrew

brew list repr

# If not found, reinstall
brew install repr
3

If installed via pipx

pipx list | grep repr

# If not found, reinstall
pipx install repr-cli

# Make sure pipx bin dir is in PATH
pipx ensurepath
Close and reopen your terminal.
4

Verify installation

repr --version
Should show: repr version 0.2.0 (or similar)

​
Debugging Commands

When reporting issues or digging deeper, these commands help:

​
Check Version

repr --version

​
Check Auth Status

repr whoami
Output: 
Authenticated as: you@example.com
Account ID: usr_abc123
Mode: Cloud (connected)
Or: 
Not authenticated (local-only mode)

​
Check Configuration

# Show all config
repr config show

# Show specific setting
repr config show llm.default
repr config show llm.local_api_url

# Export as JSON (easier to share)
repr config show --json

​
Check Repo Status

repr repos --json
Returns JSON with all tracked repos, their paths, and status.

​
Check Hook Queue

repr hooks status --json
Shows pending commits waiting to be processed.

​
Check Privacy/Network Audit

repr privacy audit --days 7 --json
Shows all network activity for the last 7 days in JSON format.

​
Run Full Diagnostics

repr doctor --verbose
More detailed output than standard repr doctor.

​
Getting Help

​
1. Check the Docs

​
2. Run Doctor

repr doctor
This catches most issues automatically.

​
3. Check GitHub Issues

Search existing issues: https://github.com/repr-app/cli/issues Someone might have already solved your problem.

​
4. File a Bug Report

If nothing works, file an issue: 
# Collect debug info
repr doctor --verbose > debug-info.txt
repr config show --json >> debug-info.txt

# Attach debug-info.txt to your GitHub issue
Include:
  • What you were trying to do
  • What happened (error message)
  • repr --version
  • Output of repr doctor
  • Operating system (macOS, Linux, Windows)

​
Edge Cases

​
repr Works, But Stories Are Bad Quality

Not a bug—this is an LLM problem. Fixes:
  1. Try a different model: 
    ollama pull codellama
repr config set llm.local_model codellama
  2. Use a better LLM via BYOK: 
    repr llm add openai
repr llm use byok:openai
    OpenAI’s models are generally better than open-source local models.
  3. Add context with custom prompts: 
    repr generate --prompt "Focus on user impact and business value"
  4. Edit stories manually: 
    repr story edit <id>
    Polish them yourself. Repr gives you the 80% draft, you add the 20% polish.

​
repr Is Too Slow

Causes:
  • Local LLM is underpowered
  • Processing too many commits at once
  • Disk I/O bottleneck
Fixes: 
# Use smaller batch size
repr generate --batch-size 3

# Switch to cloud (faster)
repr generate --cloud

# Or use BYOK with a fast provider (Groq is very fast)
repr llm add groq
repr llm use byok:groq

​
“Permission denied” Errors

Symptoms: 
Error: Permission denied
Cannot write to ~/.repr/stories
Fix: 
# Check permissions
ls -la ~/.repr

# Fix if needed
chmod -R u+w ~/.repr
If on a corporate machine with restrictive permissions, you might need to: 
# Use a different directory
repr config set storage.path ~/Documents/repr-data

​
Still Stuck?

If none of this helps:
  1. Try a fresh install: 
    # Backup your data first
repr data backup --output ~/repr-backup.json

# Uninstall
brew uninstall repr  # or: pipx uninstall repr-cli

# Reinstall
brew install repr  # or: pipx install repr-cli

# Restore
repr data restore ~/repr-backup.json
  2. Ask for help:
Include the output of repr doctor when asking for help. Makes debugging way easier.