Common issues and how to resolve them.

Hooks don’t fire

Copilot CLI auto-discovers hooks.json from the current working directory. Make sure:

  1. You’re running Copilot CLI from the same directory where you ran infinium-copilot init.
  2. hooks.json exists there:
ls -la hooks.json
cat hooks.json | head
  1. Your Copilot CLI is a modern build (GA or later). Older internal betas didn’t have the hook system.

If hooks.json is missing, re-run:

infinium-copilot init
# Choose [2] Reconfigure hooks

infinium-copilot command not found

The infinium-copilot 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_copilot_cli_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-copilot test fails with authentication error

Connection failed: 401 Unauthorized

Your agent ID or secret is incorrect. Update them:

infinium-copilot 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-copilot test fails with connection error

Connection failed: Connection refused
  • Check your internet connection
  • Verify the API URL: infinium-copilot 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-copilot status

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

  1. Check if hooks are installed:

infinium-copilot status shows the hooks path. If it’s missing, re-run:

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

infinium-copilot retry
  1. Check the error log:
infinium-copilot errors

Recent network, auth, or payload errors show up here with timestamps.

Traces look thin or “inconclusive” in Maestro

Copilot CLI does not emit a final-assistant-message event, so the connector synthesizes a response summary from the last tool result + session end reason (e.g. bash -> All 42 tests passed (session ended: complete)).

If Maestro still flags a trace as inconclusive:

  • Make sure sessionEnd actually fires (some Copilot exit paths may skip it). If not, the connector falls back to the stale-session cleanup path.
  • Check infinium-copilot status — the “Last error” line will show any payload-build issues.

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-copilot 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-copilot init

The connector walks up the directory tree looking for .infinium/config.json, so subdirectories inherit the project’s config automatically.

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"

Too many traces (per-turn flushing)

If you see a trace on every tool call, you probably have CONNECTOR_FLUSH_ON_STOP=true or picked “per-turn” during init. Switch back to per-session:

infinium-copilot init
# Choose [3] Change trace granularity
# Pick [2] Per session

Stale session files

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

infinium-copilot cleanup

This removes session files older than 30 minutes. Adjust with --max-age:

# Remove files older than 10 minutes
infinium-copilot cleanup --max-age 600

Reinstalling after uninstall

pip install infinium-copilot-cli-connector
infinium-copilot init
infinium-copilot test

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