● Diagnosis

Troubleshooting

Solutions to the most common runtime errors and environment issues.

"command not found: eve-preflight"

Occurs when running eve-preflight directly without a global install or without using npx.

Fix 1: Run via npx directly (recommended)

$ npx eve-preflight

Fix 2: Install globally or link locally

$ npm install -g eve-preflight

Another process is already listening on the default preflight port (3001).

Fix: Pass a custom port flag or environment variable

$ npx eve-preflight -p 3002

Preflight tried to forward a request to your Eve dev server at http://localhost:3000, but no server was responding.

Fix: Start your Eve agent dev server first

$ npx eve dev

If your Eve server is running on a non-standard port (e.g. 4000), use -t 4000.

Preflight must be executed inside the root of a valid Eve project containing an eve.config.ts file or an agent/ directory.

Fix: cd into your Eve project directory before running

$ cd my-eve-agent
$ npx eve-preflight