PHANTOM v4.0.0 DOCS
Website GitHub

Troubleshooting

Owner: PhantomPM User Docs Team
Last Updated: 2026-02-13
Status: Real

PHANTOM command fails to run

Symptoms:

  1. command not found: phantom

Fix:

  1. run from repo via npm run phantom -- --help
  2. ensure install path is in PATH when installer is available

Build fails in modules package

Symptoms:

  1. TypeScript reports no inputs for packages/modules

Fix:

  1. ensure packages/modules/src/index.ts exists
  2. rerun npm run build

CLI fails with duplicate command error

Symptoms:

  1. startup error about duplicate context command

Fix:

  1. ensure using build with corrected command/subcommand architecture
  2. rerun build and retry phantom --help

Integration command reports unknown target

Symptoms:

  1. unsupported integration target

Fix:

  1. run phantom integrate scan to view candidates
  2. use supported targets listed by command help

Swarm output seems inconsistent

Explanation:

  1. current swarm behavior is Beta and may include simulated elements

Reference:

Need debug snapshot

Use:

The Phantom Supervisor: Automated Troubleshooting

If the system crashes, the PhantomSupervisor is your first line of defense.

Logs

You can view the internal logs for the supervisor and the server by running:

tail -f ~/.phantom/logs/supervisor.log
tail -f ~/.phantom/logs/server.log

Common Auto-Fixes

  1. Server Restart: If the server becomes unresponsive, the supervisor will reboot it automatically within 5 seconds.
  2. AI Provider Fallback: If you see “Switching to Fallback Provider” in the UI, the system has detected a failure in your primary AI connection and is routing through a backup.
  3. Port Conflicts: Phantom defaults to port 3333. If this is blocked, the supervisor will attempt to notify you and recommend a port shift.

When to Manual Reset

If the supervisor enters an “Error Loop” (restarting more than 5 times in 1 minute), it will halt. In this case:

  1. Run phantom health to check the diagnostic report.
  2. Run phantom boot --force to re-download the matrix UI and reset core configurations.
phantom doctor
phantom status --json

Include output in issue report with OS and Node version.