Support

Troubleshooting

Common issues and how to fix them.

Installation Issues

Installer fails with permission error

The script can't write to ~/.pyckle/ or modify Claude Code settings.

Solution

Check directory permissions:

ls -la ~/.pyckle
ls -la ~/.claude

If directories don't exist or have wrong permissions:

mkdir -p ~/.pyckle ~/.claude
chmod 755 ~/.pyckle ~/.claude

Command not found: pyckle

After installation, the pyckle command isn't recognized.

Solution

The CLI may not be in your PATH. Try:

# Check if it's installed
pip show pyckle

# If installed, find the location
which pyckle || pip show pyckle | grep Location

# Add to PATH (add to your ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.local/bin:$PATH"

Python version error

Installer reports Python version incompatibility.

Solution

Pyckle requires Python 3.10+. Check your version:

python3 --version

If you have an older version, consider using pyenv to install a newer Python.

Hook Issues

Context not appearing in Claude responses

You indexed your project but Claude doesn't seem to have context.

Solution

  1. 1. Make sure you're in an indexed project directory: 
    pyckle projects
  2. 2. Check that the hook is configured: 
    cat ~/.claude/settings.json | grep -A5 hooks
  3. 3. Check the hook log for errors: 
    cat ~/.pyckle/hook.log
  4. 4. Test the routing manually: 
    echo "How does authentication work?" | pyckle route

Hook timeout or slow responses

Claude Code takes a long time to start responding.

Solution

Check your connection to the Pyckle API:

pyckle status

If latency is high, it may be a network issue. The hook typically adds ~50ms. If you're seeing 1s+, check:

  • Your internet connection
  • VPN or firewall settings that might slow API calls
  • Try from a different network to isolate the issue

Hook not running at all

The hook doesn't seem to execute when you send prompts.

Solution

Re-install the hook:

pyckle hook install

Then restart Claude Code completely (not just a new chat).

Indexing Issues

Indexing stuck or very slow

The pyckle index command takes forever or hangs.

Solution

Large codebases take longer. Check progress:

pyckle index . --verbose

If it's genuinely stuck, it may be hitting a specific file. Try excluding large directories:

pyckle index . --exclude node_modules --exclude .git --exclude dist

Index upload fails

Chunks are generated but upload to Pyckle fails.

Solution

Check your API key and connection:

pyckle status

If your subscription is expired or invalid, you'll see an error. Visit your dashboard to check subscription status.

Some files not indexed

Certain files in your project don't appear in search results.

Solution

Pyckle indexes common code file types. Check which files were indexed:

pyckle projects --details

By default, we index:

.py .js .ts .tsx .jsx .go .rs .java .rb .php .c .cpp .h .hpp .cs .swift .kt .scala .sh .sql .md

Binary files, images, and vendor directories are excluded.

Authentication Issues

Invalid API key error

Commands fail with "Invalid API key" or "Unauthorized".

Solution

Re-authenticate with a fresh key from your dashboard:

pyckle auth pk_live_your_new_key

If you've regenerated your key in the dashboard, the old key is invalidated.

Subscription expired

Commands fail with subscription-related errors.

Solution

Check your subscription status in the dashboard. If expired, renew to restore access. Your indexed data is retained for 30 days after expiration.

Complete Reset

If nothing else works, do a complete reinstall:

# Remove everything
pyckle uninstall

# Clear any leftover files
rm -rf ~/.pyckle

# Reinstall fresh
curl -sL pyckle.dev/install | bash

Note: This will remove your local configuration. You'll need to re-authenticate and re-index your projects.

Still Stuck?

If you've tried everything above and still have issues, gather this info before contacting support:

  • Your logs: cat ~/.pyckle/hook.log
  • Your OS and Python version
  • Exact steps to reproduce the issue
Contact Support

We typically respond within 24 hours.