Skip to content

Troubleshooting

Jump to bottom
Manit Arora edited this page Oct 21, 2026 · 3 revisions

Troubleshooting

Use this checklist to collect useful diagnostic information while minimizing exposure of private data.

1. Confirm the version and environment

axiom version
python --version
axiom --help

If multiple Python environments are installed, make sure the shell is invoking the axiom executable you intended. Confirm ~/.local/bin is on PATH when using the user-scoped installer.

2. Run workspace diagnostics

axiom doctor
axiom doctor --json
axiom status --json

Review workspace selection, axiom.yaml parsing, filesystem permissions, free disk space, Python compatibility, and missing imports. The checks are read-only and do not repair the project automatically.

3. GUI or API errors

  • Start the Control Center using axiom gui from the intended project directory.
  • Try axiom gui --no-open if you need to copy the local URL yourself.
  • For a daemon issue, start it separately with axiom daemon --host 127.0.0.1 --port 0 and inspect the printed address and logs.
  • Capture any request/correlation identifier shown by the GUI or API response.
  • Do not expose the daemon beyond loopback unless you have consciously evaluated the network/security consequences.

4. Create a support bundle

axiom support-bundle --output ./axiom-support-bundle.zip

Open the ZIP before sharing it. The intended archive is limited to diagnostic/environment JSON and a static readme, but metadata minimization is not the same as a guarantee of anonymity in every context.

5. Report a reproducible issue

Include:

  • AXIOM version and operating system;
  • Python version and installation method;
  • the exact command or Control Center path;
  • expected versus actual behavior;
  • the smallest safe reproducer;
  • sanitized diagnostic check IDs or request ID, when available.

Do not include credentials, API keys, passwords, private dataset rows, proprietary model weights, unredacted logs, or a support bundle you have not inspected.

File the report at GitHub Issues. For potential security vulnerabilities, follow the repository's Security page instead of posting sensitive technical details publicly.

AXIOM AI source repository · Issues · MIT license

Clone this wiki locally