Skip to main content

Troubleshooting

Common issues and how to fix them.

CLI won't start​

Error: command not found: ethos

The CLI isn't on your PATH. If you installed via npm install -g, open a new terminal — your shell may not have picked up the new binary yet. If you used nvm, ensure you're on Node 24:

nvm use 24
ethos --version

If it's still missing, reinstall:

npm install -g @ethosagent/cli

Error: config.yaml not found

The setup wizard didn't complete. Delete ~/.ethos/ and re-run setup:

rm -rf ~/.ethos
ethos setup

API errors​

AuthenticationError: invalid x-api-key

Your API key is missing or wrong.

export ANTHROPIC_API_KEY="sk-ant-..."
ethos chat

Verify the key works:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5-20251001","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

RateLimitError: rate_limit_exceeded

You're hitting API rate limits. Options:

  1. Wait and retry — limits reset per minute
  2. Switch to a smaller model for development (claude-haiku-4-5-20251001)
  3. Add more API keys and use AuthRotatingProvider from @ethosagent/llm-anthropic

Session issues​

Conversation history isn't persisting

Check that ~/.ethos/sessions.db exists and is writable:

ls -la ~/.ethos/sessions.db
sqlite3 ~/.ethos/sessions.db ".tables"

If the DB is corrupted, back it up and delete it:

cp ~/.ethos/sessions.db ~/.ethos/sessions.db.bak
rm ~/.ethos/sessions.db
ethos chat   # creates a fresh DB

Agent forgets context mid-conversation

The agent uses getMessages(sessionId, { limit: 50 }) by default. For very long conversations, earlier context is dropped. Options:

  1. Use /new to start a fresh session when context is stale
  2. Ask the agent to save key facts to memory: "Remember that X"
  3. Increase the message limit in config (uses more tokens per turn)

Tool errors​

Tool 'X' not found

The tool isn't registered. Check:

  1. The tool name matches exactly (case-sensitive)
  2. The tool's isAvailable() returns true
  3. The tool is in the personality's toolset.yaml
# In the CLI:
/tools   # lists all registered tools

Tool results are truncated

Large tool outputs are trimmed to fit the context budget. To get more output:

  1. Ask the agent to use pagination: "Read the file 100 lines at a time"
  2. Reduce the number of parallel tool calls
  3. Increase resultBudgetChars in AgentLoop config (raises token costs)

Personality issues​

Personality 'X' not found

The personality directory doesn't exist or is missing required files:

ls ~/.ethos/personalities/
ls ~/.ethos/personalities/myid/
# Should contain: ETHOS.md, config.yaml, toolset.yaml

Personality isn't hot-reloading

The file-based loader caches on config.yaml mtime. After editing personality files, touch the config:

touch ~/.ethos/personalities/myid/config.yaml

TypeScript errors​

The rest of this page covers issues you'll only hit when working from a source checkout (contributing, building plugins, or running from the monorepo). If you installed via npm install -g @ethosagent/cli, you can stop here.

Type 'X' is not assignable to type 'Y'

If you're extending Ethos, make sure you're using the same @ethosagent/types version as the host app. Mismatched versions cause interface incompatibilities.

Check versions:

pnpm list @ethosagent/types --recursive

noNonNullAssertion lint error

Biome blocks ! non-null assertions. Use a guard instead:

// Wrong
const val = map.get(key)!;

// Correct
const val = map.get(key);
if (!val) throw new Error('expected key');

Build issues​

pnpm build fails with missing exports

After adding a new workspace package, add its path alias to the root tsconfig.json:

{
  "paths": {
    "@ethosagent/mypackage": ["./extensions/mypackage/src"]
  }
}

better-sqlite3 fails to install

Native module compilation failed. Install build tools:

# macOS
xcode-select --install

# Ubuntu/Debian
sudo apt-get install build-essential python3

Then reinstall:

pnpm install --force

Getting help​

When filing a bug, include:

  • Node version (node --version)
  • pnpm version (pnpm --version)
  • OS and version
  • Relevant error message and stack trace
  • Steps to reproduce