​

Troubleshooting Guide

​

Setup Wizard Issues

​

Wizard shows “No TTY detected” when using curl pipe

# Option A: Run install.sh first, then the wizard manually
curl -sSL https://raw.githubusercontent.com/albinotonnina/echos/main/install.sh | bash
# Follow the printed instructions to run: cd ~/echos && pnpm wizard

# Option B: Download first, then run (preserves TTY)
curl -sSL https://raw.githubusercontent.com/albinotonnina/echos/main/install.sh -o /tmp/install-echos.sh
bash /tmp/install-echos.sh

​

API key validation fails but key is correct

1. Check network connectivity — the wizard makes outbound HTTPS requests to api.anthropic.com, api.openai.com, api.telegram.org
2. Use --skip-validation to bypass live checks: pnpm wizard --skip-validation
3. Corporate proxies or firewalls may block API calls — configure HTTPS_PROXY env var before running wizard

​

”I have Claude Pro/Max subscription - can I use it for EchOS?”

• Claude Pro/Max subscriptions ($20-$200/month) are for using Claude through Anthropic’s web, desktop, and mobile apps only
• They do NOT provide API access for programmatic integration
• EchOS requires a separate Anthropic API account with pay-as-you-go billing
• API costs are typically much lower than subscriptions for automated use cases (often ~$5/month for typical personal use)

1. Sign up for Anthropic API access at https://console.anthropic.com/
2. Add credits or set up billing
3. Generate an API key under Settings → API Keys
4. Use that key in EchOS .env file

​

Wizard exits immediately in --non-interactive mode

• ALLOWED_USER_IDS
• At least one LLM key: ANTHROPIC_API_KEY or LLM_API_KEY

# Anthropic
ANTHROPIC_API_KEY=sk-ant-... ALLOWED_USER_IDS=123456789 pnpm wizard --non-interactive
# Other provider (e.g. Groq)
LLM_API_KEY=gsk_... DEFAULT_MODEL=groq/llama-3.3-70b-versatile ALLOWED_USER_IDS=123456789 pnpm wizard --non-interactive

​

.env file has wrong permissions

chmod 0600 .env
ls -la .env  # should show: -rw------- 1 you ...

​

”No .env file found. Run: pnpm wizard” on startup

pnpm wizard

ANTHROPIC_API_KEY=... ALLOWED_USER_IDS=... pnpm wizard --non-interactive --skip-validation
# or with a non-Anthropic provider:
LLM_API_KEY=... DEFAULT_MODEL=groq/llama-3.3-70b-versatile ALLOWED_USER_IDS=... pnpm wizard --non-interactive --skip-validation

​

Build and Installation Issues

​

Cannot find package ‘@echos/shared’ (or other @echos/* packages)

Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@echos/shared'

1. Build all packages first:
   Copy

   Ask AI

   pnpm build
   
2. If build fails, clean and rebuild:
   Copy

   Ask AI

   pnpm clean
   pnpm install
   pnpm build
   
3. Verify path mappings: The root tsconfig.json includes these mappings for tsx:
   Copy

   Ask AI

   "paths": {
     "@echos/shared": ["./packages/shared/src/index.ts"],
     "@echos/core": ["./packages/core/src/index.ts"],
     // ... etc
   }
   

​

LanceDB Native Module Errors

Error: Cannot find module '@lancedb/lancedb-darwin-x64'
Error: Cannot find module '@lancedb/lancedb-darwin-arm64'

1. Intel Macs (darwin-x64):
   • The project is configured to use LanceDB 0.22.3 (last version with Intel Mac support)
   • This is set in packages/core/package.json
   • If you see this error, run: pnpm install --force
2. Apple Silicon Macs (darwin-arm64):
   • Should work with LanceDB 0.26.2+
   • If issues persist, try: pnpm install --force
3. Linux/Windows:
   • LanceDB should auto-install the correct native binding
   • Run: pnpm install --force if needed
4. Check what’s installed:
   Copy

   Ask AI

   ls node_modules/.pnpm/@lancedb*/
   

​

Configuration Errors

Error: Invalid configuration:
  telegramBotToken: Required
  allowedUserIds: Required
  anthropicApiKey: Required

1. Copy the example file:
   Copy

   Ask AI

   cp .env.example .env
   
2. Edit .env and fill in required values:
   Copy

   Ask AI

   TELEGRAM_BOT_TOKEN=your_token_from_botfather
   ALLOWED_USER_IDS=123456789,987654321
   # Anthropic:
   ANTHROPIC_API_KEY=sk-ant-your-key-here
   # or another provider (e.g. Groq):
   # LLM_API_KEY=gsk_...
   # DEFAULT_MODEL=groq/llama-3.3-70b-versatile
   
3. Get your Telegram user ID:
   • Message @userinfobot on Telegram
   • Add your ID to ALLOWED_USER_IDS
4. Verify the file loads (Node 20.6+):
   Copy

   Ask AI

   # The start script uses --env-file flag
   pnpm start
   

​

Runtime Issues

​

Telegram Bot Conflicts

GrammyError: Call to 'getUpdates' failed! (409: Conflict: 
terminated by other getUpdates request; make sure that only 
one bot instance is running)

• Local processes on your machine
• Remote deployments (VPS, cloud instances, etc.)
• Docker containers
• Another developer’s machine using the same bot token

​

Step 1: Check local processes

ps aux | grep "tsx.*index.ts"
# Or more broadly
ps aux | grep echos
# If only the grep command appears, no local instances are running

​

Step 2: Check Docker containers

docker ps | grep echos
# If no output, no containers running

​

Step 3: Check bot webhook status

./scripts/check-telegram-bot.sh status
# Look for "url" field - should be empty "" for polling

​

Step 4: Clear webhook and pending updates

./scripts/check-telegram-bot.sh delete-webhook
# This drops pending updates and allows polling

​

Step 5: Check remote deployments

# SSH to your server
ssh user@your-server

# Check for running processes
ps aux | grep echos

# Check Docker containers
docker ps

# Stop if found
docker compose down
# Or kill the process
pkill -f "tsx.*index.ts"

​

Step 6: Wait for timeout

​

Step 7: Stop all instances

# Stop local processes
pkill -f "tsx.*index.ts"

# Stop Docker
docker compose down

# Clear webhook
./scripts/check-telegram-bot.sh delete-webhook

# Wait 60 seconds
sleep 60

# Restart
pnpm start

# Set webhook URL (HTTPS required)
curl -X POST "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setWebhook" \
  -d "url=https://your-domain.com/telegram/webhook" \
  -d "secret_token=your_random_secret_here"

# Verify webhook
curl "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/getWebhookInfo"

TELEGRAM_WEBHOOK_URL=https://your-domain.com/telegram/webhook
TELEGRAM_WEBHOOK_SECRET=your_random_secret_here

​

Redis Connection Errors

Error: connect ECONNREFUSED 127.0.0.1:6379

1. Use the Redis management script (recommended):
   Copy

   Ask AI

   # Check status
   pnpm redis:status
   
   # Start Redis (auto-detects platform)
   pnpm redis:start
   
   # Verify connection
   pnpm redis:health
   
2. Manual platform-specific start (if script fails):
   Copy

   Ask AI

   # macOS
   brew services start redis
   
   # Linux (systemd)
   sudo systemctl start redis
   
   # Docker
   docker run -d -p 6379:6379 --name echos-redis redis:7-alpine
   
3. Check Redis URL in .env:
   Copy

   Ask AI

   REDIS_URL=redis://localhost:6379
   
4. Verify Redis is running:
   Copy

   Ask AI

   redis-cli ping
   # Should return: PONG
   

​

Database/Storage Errors

Error: unable to open database file
Error: ENOENT: no such file or directory

1. Create data directories:
   Copy

   Ask AI

   mkdir -p data/db data/knowledge data/sessions
   
2. Check permissions:
   Copy

   Ask AI

   ls -la data/
   # Ensure directories are writable
   
3. Check paths in .env:
   Copy

   Ask AI

   KNOWLEDGE_DIR=./data/knowledge
   DB_PATH=./data/db
   SESSION_DIR=./data/sessions
   
4. Clean state (CAUTION: deletes all data):
   Copy

   Ask AI

   rm -rf data/
   mkdir -p data/db data/knowledge data/sessions
   pnpm start
   

​

Development Issues

​

TypeScript Errors

1. Check all packages:
   Copy

   Ask AI

   pnpm typecheck
   
2. Rebuild after package changes:
   Copy

   Ask AI

   pnpm build
   
3. Use watch mode during development:
   Copy

   Ask AI

   pnpm dev
   

​

Vitest Test Failures

1. Run tests:
   Copy

   Ask AI

   pnpm test
   
2. Run specific test file:
   Copy

   Ask AI

   pnpm vitest packages/shared/src/security/url-validator.test.ts
   
3. Watch mode:
   Copy

   Ask AI

   pnpm test:watch
   

​

Storage Sync Issues

​

Manually added/edited markdown file not appearing in search

• On startup, EchOS reconciles all markdown files with SQLite and LanceDB automatically
• While running, a file watcher picks up any add, change, or unlink events in real time (debounced 500 ms)

1. Check the file has a valid id in frontmatter — files without an id field are silently skipped:
   Copy

   Ask AI

   ---
   id: some-unique-id
   type: note
   title: My Note
   created: 2026-02-17T12:00:00.000Z
   updated: 2026-02-17T12:00:00.000Z
   tags: []
   links: []
   category: uncategorized
   ---
   
2. If you added the file while the app was stopped — just restart. The startup reconciler will pick it up:
   Copy

   Ask AI

   pnpm start
   
3. If you added the file while the app is running — the file watcher should index it within ~1 second. If it doesn’t appear after a few seconds, check the logs:
   Copy

   Ask AI

   pnpm start | pnpm exec pino-pretty
   # Look for "File watcher: upserted" or "Reconciler:" log lines
   
4. Enable debug logging to see all reconciler/watcher events:
   Copy

   Ask AI

   LOG_LEVEL=debug pnpm start
   

​

Search results show stale content after editing a note externally

​

Memory Issues

​

Memory stored but not recalled after /reset

• remember_about_me stores facts permanently in SQLite (survives /reset)
• On every new session, the top 15 memories by confidence are injected into the system prompt automatically
• Additional memories beyond the top 15 are searchable via recall_knowledge

1. It may be beyond position 15 — ask explicitly: “recall what you know about X” to trigger recall_knowledge
2. The search uses keyword matching — use related terms: “recall what you know about my birthday” or “recall birth year”
3. Increase confidence when storing important facts: the agent can be told “remember this with high confidence”

​

Content Status Issues

• Articles saved via save_article start with status: saved (reading list), not status: read (knowledge)
• If the agent is mixing them, remind it: “distinguish between saved articles and things I’ve actually read”
• You can filter: “show only what I’ve actually read about X”

• Ask: “show my reading list” — the agent calls list_notes(status="saved")
• Articles saved before this feature was introduced may have status: null — they won’t appear in filtered lists; use update_note or mark_content to set their status

• This is intentional: when you begin actively discussing a saved article, the agent auto-marks it read
• To prevent this, tell the agent you’re just asking about the topic in general, not discussing that specific article

• save_conversation is only called when you explicitly ask (“save this conversation” or “save what we discussed about X”)
• It is never called automatically

​

CLI Issues (pnpm echos)

​

Empty response — agent runs but prints nothing

LOG_LEVEL=info pnpm echos "hello"

​

Startup logs cluttering the output

1. Check whether LOG_LEVEL is exported in your shell: echo $LOG_LEVEL
2. Unset it or set it to warn: unset LOG_LEVEL

​

Shell parse errors (zsh: parse error near '\n')

# Wrong — zsh interprets `?` and `>`
pnpm echos what notes do I have about TypeScript?

# Correct
pnpm echos "what notes do I have about TypeScript?"

​

History not persisting between sessions

• Check write permissions: ls -la ~/.echos_history
• The file is created on the first clean exit (exit / quit / Ctrl+D). Kills via kill -9 skip the save.

​

YouTube Transcript Issues

​

”Unable to save this video” / YouTube transcript fails

• Bot responds with “I was unable to save this video”
• Logs show: YouTube transcript unavailable [IpBlocked] or YouTube transcript unavailable [RequestBlocked]

1. Local machine: No setup required — home IPs are not blocked by YouTube.
2. Docker / VPS: The Docker image includes all required JS dependencies. No extra steps needed.

WEBSHARE_PROXY_USERNAME=your_username
WEBSHARE_PROXY_PASSWORD=your_password

​

Twitter / X Issues

​

”Unable to save this tweet” / Tweet fetch fails

• Agent responds with “I wasn’t able to save that tweet” or similar
• Logs show: save_tweet failed with an error message

1. Check the URL format — the plugin accepts these formats:
   • https://twitter.com/<user>/status/<id>
   • https://x.com/<user>/status/<id>
   • https://mobile.twitter.com/<user>/status/<id>
   • https://fxtwitter.com/<user>/status/<id> / https://vxtwitter.com/<user>/status/<id>
2. Check that the tweet exists and is public — private/protected accounts and deleted tweets cannot be fetched.
3. Enable debug logging to see the full error from the FxTwitter API:
   Copy

   Ask AI

   LOG_LEVEL=debug pnpm echos "save this tweet: https://x.com/..."
   
4. FxTwitter rate limiting — the FxTwitter API is a free public service and may occasionally rate-limit requests. Wait a moment and try again.

​

Agent uses create_note instead of save_tweet

• Telegram: Send /reset
• CLI: Exit and restart (exit or Ctrl+D)

​

Getting Help

1. Check the logs: EchOS uses Pino for structured logging
   Copy

   Ask AI

   pnpm start | pnpm exec pino-pretty
   
2. Enable debug logging: Set LOG_LEVEL=debug in .env
3. Check system requirements:
   • Node.js 20+ (node --version)
   • pnpm 9+ (pnpm --version)
   • Redis running (redis-cli ping)
   • Enough disk space for embeddings/vectors
4. Review security docs: See Security
5. Architecture overview: See Architecture