Common issues and how to resolve them.

infinium-claude command not found

The infinium-claude executable is installed to Python’s Scripts directory, which may not be on your system PATH.

Quick fix — use the module directly:

python -m infinium_connector <command>

Permanent fix — add Python’s Scripts directory to your PATH:

  • Windows: Add C:\Users\{you}\AppData\Local\Python\{version}\Scripts to your system PATH via Environment Variables
  • macOS/Linux: Usually works automatically. If not, check python -m site --user-base and add the bin subdirectory to your shell profile

infinium-claude test fails with authentication error

Connection failed: 401 Unauthorized

Your agent ID or secret is incorrect. Update them:

infinium-claude update-credentials

Make sure you’re using the agent secret (not your personal API key) from the Infinium platform. You can generate one at Settings > API Keys > Agent tab.

infinium-claude test fails with connection error

Connection failed: Connection refused
  • Check your internet connection
  • Verify the API URL: infinium-claude status shows the current URL
  • If using a custom base URL, make sure it’s correct

Traces not appearing in Infinium

  1. Check if tracing is paused:
infinium-claude status

If it shows PAUSED, resume with infinium-claude resume.

  1. Check if hooks are installed:

infinium-claude status shows hook locations. If no hooks are listed, re-run:

infinium-claude init
# Choose [2] Reconfigure hooks
  1. Check for failed traces:
infinium-claude status
# Look for "Pending retry: N failed trace(s)"

infinium-claude retry
  1. Verify credentials are configured:

infinium-claude status should show an Agent ID and Secret: configured. If not, run infinium-claude init.

Wrong agent receiving traces

If you have per-project configs and traces are going to the wrong agent:

# Check which config is active in the current directory
infinium-claude status
# Look at "Config from:" line
  • Config from: project (...) — using project-level config
  • Config from: environment variables — env vars are overriding

To set up project-specific credentials:

cd /path/to/your/project
infinium-claude init
# Enter the correct Agent ID and Secret

Keyring errors on Linux

If you see warnings about keyring not being available, your system may not have a secret service running.

Option 1: Install a secret service:

# Ubuntu/Debian
sudo apt install gnome-keyring

# Or use KDE Wallet
sudo apt install kwalletmanager

Option 2: Use environment variables instead:

export INFINIUM_AGENT_SECRET="your-secret"

Stale session files

If temporary session files accumulate (e.g., after crashes):

infinium-claude cleanup

This removes session files older than 1 hour. Adjust with --max-age:

# Remove files older than 30 minutes
infinium-claude cleanup --max-age 1800

Reinstalling after uninstall

pip install infinium-claude-code-connector
infinium-claude init
infinium-claude test

Your previous keyring credentials may still exist. The setup wizard will detect them and offer to reuse or update.