Common issues and how to resolve them.

Hooks don’t fire at all

Codex’s hook system is feature-flagged and disabled by default. Verify:

# Should show codex_hooks = true in the output
cat ~/.codex/config.toml

# If missing, enable it:
codex features enable codex_hooks

If that doesn’t work, add it manually to ~/.codex/config.toml:

[features]
codex_hooks = true

Hooks don’t fire on Windows

Versions of Codex CLI before v0.119.0 gated hooks off on Windows. Check your version:

codex --version

If it’s below v0.119.0, upgrade:

# Via your Codex installation method — typically:
pip install --upgrade openai-codex
# or your package manager of choice

The fix was openai/codex#17268, merged on 2026-04-09 and shipped in v0.119.0 on 2026-04-10.

infinium-codex command not found

The infinium-codex 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_codex_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-codex test fails with authentication error

Connection failed: 401 Unauthorized

Your agent ID or secret is incorrect. Update them:

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

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

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

  1. Check if hooks are installed:

infinium-codex status shows the hooks path. If it’s missing or codex_hooks isn’t enabled, re-run:

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

infinium-codex retry
  1. Verify credentials are configured:

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

  1. Check the error log:
infinium-codex errors

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

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

The connector walks up the directory tree looking for .infinium/config.json, so subdirectories of a project 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"

Stale session files

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

infinium-codex cleanup

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

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

Reinstalling after uninstall

pip install infinium-codex-connector
infinium-codex init
infinium-codex test

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