Troubleshooting

Common issues and how to resolve them.

The doctor command

Always start with diagnostics:

eqho-eval doctor

This checks:

  • Node.js version (20+ required)
  • eqho-eval version
  • API key configuration
  • Eqho API connectivity
  • Backend proxy connectivity
  • promptfoo installation
  • Project configuration
  • Provider connectivity (if config exists)

Auto-fix

eqho-eval doctor --fix

Attempts to automatically resolve detected issues, including better-sqlite3 native module problems.

Common issues

"eqho-eval: command not found"

The CLI isn't in your PATH. Reinstall globally:

npm i -g eqho-eval

Verify it's installed:

which eqho-eval
eqho-eval --version

Tip: eqho-evals (with an "s") also works as an alias.

"promptfoo: command not found"

Install promptfoo globally:

npm i -g promptfoo

Or if it's installed but not found, try:

npx promptfoo --version

Authentication errors

"Not authenticated" or "Invalid token":

# Re-authenticate
eqho-eval auth --key <your-api-key>

# Verify
eqho-eval doctor

"JWT expired":

Tokens expire after 7 days. Re-authenticate:

eqho-eval auth --key <your-api-key>

Wrong backend URL:

eqho-eval auth --key <key> --backend https://evals.eqho-solutions.dev

Provider connectivity failures

If eqho-eval eval reports provider errors during pre-flight:

  1. Check which providers failed:

    eqho-eval doctor

  2. Verify the model ID is correct — run eqho-eval providers list to see available models

  3. Check if the backend proxy is up:

    curl https://evals.eqho-solutions.dev/api/v1/models

  4. Skip pre-flight to run evals anyway:

    eqho-eval eval --skip-preflight

"ERESOLVE" npm errors

If you see dependency resolution errors when installing:

# eqho-eval is a global CLI tool — install it globally
npm i -g eqho-eval

# Do NOT run npm install in your eval project directory
# The eval project doesn't have its own package.json

better-sqlite3 native module errors

promptfoo uses better-sqlite3 for caching. If you see native module errors:

eqho-eval doctor --fix

Or manually:

npm rebuild better-sqlite3

Eval results show all failures

  1. Check your .env file — make sure OPENAI_API_KEY and OPENAI_BASE_URL are set
  2. Check the proxy — eqho-eval doctor verifies connectivity
  3. Check model IDs — run eqho-eval providers list to verify model names
  4. Run with verbose — eqho-eval eval --verbose shows per-assertion details
  5. Try a single provider — comment out all but one provider in your config to isolate

Stale results

eqho-eval cache clear
eqho-eval eval --no-cache

Terminal width issues

If the results table looks broken or truncated:

# Use wide mode for many providers
eqho-eval results --wide

# Or view in the browser
eqho-eval view

Getting help