Troubleshooting

Solutions to common issues you might encounter when using livectx.

"API key required" Error

Make sure your API key is properly set:

Terminal
$ echo $ANTHROPIC_API_KEY # Check if key is set
Terminal
$ export ANTHROPIC_API_KEY=sk-ant-... # Set for current session

Verify your configuration:

Terminal
$ livectx validate

Generation Seems Stuck

For large repositories, generation can take 1-2 minutes due to LLM analysis. Use verbose mode to see progress:

Terminal
$ livectx generate --verbose

To speed things up:

  • Reduce max_files in your config
  • Add more patterns to exclude
  • Caching will skip unchanged files on subsequent runs

Rate Limit / 429 Errors

You've hit the API rate limit. livectx includes automatic retry with exponential backoff, but you may need to wait a moment.

Solutions:

  • Wait a few minutes and try again
  • For OpenRouter, switch to a model with higher limits:
    .livectx.yaml
    llm:
  provider: openrouter
  model: anthropic/claude-3-haiku  # Faster, higher limits
  • Reduce the size of your codebase input (fewer files)

Files Are Missing from Output

Check what's being excluded:

Terminal
$ livectx generate --verbose --dry-run

Common reasons files are skipped:

  • Listed in .gitignore
  • Binary files (images, PDFs, executables)
  • Files larger than max_file_size (default: 100KB)
  • Matched by exclude patterns in config
  • Detected as containing secrets

To include specific file types:

.livectx.yaml
include:
  - "*.md"
  - "*.yaml"
  - "*.json"

max_file_size: 204800  # Increase to 200KB

Permission Denied Errors

Run with verbose mode to see which files couldn't be read:

Terminal
$ livectx generate --verbose

Common causes:

  • Running in a directory without read permissions
  • Files owned by another user
  • Trying to write to a read-only directory

Output Files Are Too Large

Reduce the number of files included:

.livectx.yaml
max_files: 200
max_file_size: 51200  # 50KB

exclude:
  - "**/*.test.*"
  - "**/*.spec.*"
  - "**/fixtures/**"
  - "**/testdata/**"
  - "**/node_modules/**"
  - "**/vendor/**"

Invalid Configuration

Validate your configuration file:

Terminal
$ livectx validate

Common issues:

  • YAML syntax errors (check indentation)
  • Invalid provider name (use "anthropic" or "openrouter")
  • Negative values for max_files or max_file_size

API Connection Issues

Test API connectivity:

Terminal
$ livectx validate --check-api

If this fails:

  • Check your internet connection
  • Verify your API key is correct
  • Check if the API provider is experiencing issues
  • Try a different provider (switch to OpenRouter or vice versa)

Context Not Updating in CI

Check the GitHub Action logs for errors. Common issues:

  • Secret not set: Ensure ANTHROPIC_API_KEY is added to repository secrets
  • Permissions: The workflow needs contents: write permission
  • Checkout depth: Make sure the full repo is checked out

Minimal working workflow:

permissions:
  contents: write

steps:
  - uses: actions/checkout@v4

  - uses: skridlevsky/livectx@v1
    with:
      anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Still Having Issues?

  1. Check the GitHub Issues for similar problems
  2. Open a new issue with:
    • livectx version (livectx version)
    • Your OS and architecture
    • The error message
    • Your config file (without API keys)
    • Steps to reproduce