Troubleshooting Guide

Comprehensive troubleshooting guide for common ElizaOS issues including setup, development, and deployment problems

This guide covers common issues you might encounter while developing with ElizaOS and provides step-by-step solutions.

Quick Diagnostics

Before diving into specific issues, run this quick diagnostic checklist:

# Check system requirements
node --version    # Should be v23.3.0+
bun --version     # Should be 1.2.15+
git --version     # Any recent version

# Check ElizaOS installation
elizaos --version
elizaos --help

# Check project structure
ls -la            # Verify files are present
cat package.json  # Check dependencies

Installation Issues

Issue: Permission Denied During Installation

Symptoms:

npm ERR! Error: EACCES: permission denied

Solutions:

Use Node Version Manager (Recommended)

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# Restart terminal or run:
source ~/.bashrc

# Install and use Node.js
nvm install 23.3.0
nvm use 23.3.0

# Install ElizaOS CLI
npm install -g @elizaos/cli

Fix npm permissions

# Create directory for global packages
mkdir ~/.npm-global

# Configure npm
npm config set prefix '~/.npm-global'

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bashrc

Use npx instead

# Run without global installation
npx @elizaos/cli create -t project my-agent

Issue: Bun Installation Fails

Symptoms:

bun: command not found

Solutions:

Install Bun

# Linux/macOS
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
irm bun.sh/install.ps1 | iex

# Restart terminal or run:
source ~/.bashrc

Verify installation
```
bun --version
which bun
```

Manual PATH setup

# Add to ~/.bashrc or ~/.zshrc
export PATH="$HOME/.bun/bin:$PATH"
source ~/.bashrc

Issue: Node.js Version Mismatch

Symptoms:

engine "node" is incompatible with this module

Solutions:

Update Node.js

# Using nvm
nvm install 23.3.0
nvm use 23.3.0
nvm alias default 23.3.0

# Or download from nodejs.org

Check current version
```
node --version
npm --version
```

Project Creation Issues

Issue: Project Template Not Found

Symptoms:

Error: Template 'project' not found

Solutions:

Update CLI to latest version

npm update -g @elizaos/cli
elizaos --version

Use full template name

elizaos create -t project-starter my-agent

Manual template download

git clone https://github.com/elizaos/eliza.git
cp -r eliza/packages/project-starter my-agent
cd my-agent
bun install

Issue: Dependencies Installation Fails

Symptoms:

bun install failed
error: package not found

Solutions:

Clear cache and reinstall

rm -rf node_modules
rm bun.lockb
bun install

Check network connection

# Test npm registry access
npm ping

# Use different registry if needed
npm config set registry https://registry.npmjs.org/

Use npm as fallback
```
npm install
```

Development Issues

Issue: Agent Won't Start

Symptoms:

Error: Cannot find module '@elizaos/core'

Solutions:

Install dependencies
```
bun install
```
Build the project
```
bun run build
```

Check environment variables

# Copy example file
cp .env.example .env

# Edit with your values
nano .env

Verify file structure

ls -la src/
# Should contain index.ts and character.ts

Issue: Hot Reload Not Working

Symptoms:

Changes not reflected automatically
Need to restart manually

Solutions:

Use correct development command

# Use dev command for hot reload
elizaos dev

# NOT elizaos start

Check file watchers

# Linux: Increase file watcher limit
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

Verify TypeScript compilation

# Check for TypeScript errors
bun run type-check

Issue: Environment Variables Not Loading

Symptoms:

Error: Missing required environment variable

Solutions:

Check .env file exists
```
ls -la .env
cat .env
```

Verify .env format

# .env file should have:
OPENAI_API_KEY=your_key_here
# NOT: OPENAI_API_KEY="your_key_here"

Check file permissions
```
chmod 600 .env
```
Restart development server
```
# Stop with Ctrl+C
elizaos dev
```

API Integration Issues

Issue: OpenAI API Errors

Symptoms:

Error: 401 Unauthorized
Error: Rate limit exceeded

Solutions:

Verify API key

# Test API key
curl -H "Authorization: Bearer $OPENAI_API_KEY" \
  https://api.openai.com/v1/models

Check API quota

# Login to OpenAI dashboard
# Check usage and billing

Handle rate limits

// Add retry logic
const response = await openai.chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: [...],
  max_tokens: 150,
  timeout: 30000
});

Issue: Discord Bot Not Responding

Symptoms:

Bot appears online but doesn't respond
No error messages

Solutions:

Check bot permissions

# Bot needs these permissions:
# - Read Messages
# - Send Messages
# - Use Slash Commands

Verify bot token

# Check token in Discord Developer Portal
# Regenerate if necessary

Check intents

// Ensure proper intents are enabled
const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.MessageContent,
  ],
});

Debug message handling

client.on("messageCreate", (message) => {
  console.log("Received message:", message.content);
  // Add debug logging
});

Build and Deployment Issues

Issue: Build Failures

Symptoms:

Build failed with exit code 1
TypeScript errors

Solutions:

Check TypeScript configuration

# Verify tsconfig.json exists
cat tsconfig.json

# Check for syntax errors
bun run type-check

Fix import errors

// Use correct imports
import { Plugin } from "@elizaos/core";

// NOT: import { Plugin } from 'elizaos';

Clear build cache

rm -rf dist/
rm -rf .turbo/
bun run build

Check for missing dependencies
```
bun install
```

Issue: Deployment Failures

Symptoms:

Deployment failed
Application not starting

Solutions:

Check production environment

# Set production environment
NODE_ENV=production

# Check start script
npm run start

Verify environment variables

# Check all required variables are set
printenv | grep -E "(OPENAI|DISCORD|TWITTER)"

Test locally in production mode

bun run build
NODE_ENV=production bun start

Check platform-specific logs

# Railway
railway logs

# Vercel
vercel logs

# Heroku
heroku logs --tail

Performance Issues

Issue: High Memory Usage

Symptoms:

Application crashes with out-of-memory errors
Slow response times

Solutions:

Monitor memory usage

# Check memory usage
top -p $(pgrep node)

# Or use htop
htop

Implement memory limits

// PM2 configuration
module.exports = {
  apps: [
    {
      name: "eliza-agent",
      script: "dist/index.js",
      max_memory_restart: "1G",
    },
  ],
};

Optimize memory usage

// Clear unused variables
let largeObject = null;

// Use streaming for large responses
const stream = await openai.chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: [...],
  stream: true
});

Issue: Slow Response Times

Symptoms:

Long delays in bot responses
Timeout errors

Solutions:

Optimize API calls

// Use shorter prompts
const response = await openai.chat.completions.create({
  model: "gpt-3.5-turbo",
  messages: trimMessages(messages),
  max_tokens: 150,
});

Implement caching

// Cache frequent responses
const cache = new Map();

function getCachedResponse(key: string) {
  if (cache.has(key)) {
    return cache.get(key);
  }
  // Generate response and cache
}

Use async/await properly

// Parallel execution
const [response1, response2] = await Promise.all([api.call1(), api.call2()]);

Database Issues

Issue: Database Connection Failures

Symptoms:

Error: connect ECONNREFUSED
Database connection timeout

Solutions:

Check database configuration

# Verify database URL
echo $DATABASE_URL

# Test connection
psql $DATABASE_URL -c "SELECT 1;"

Check database service

# Local PostgreSQL
sudo systemctl status postgresql
sudo systemctl start postgresql

# Docker
docker ps | grep postgres

Verify credentials

# Check database credentials
# Update .env with correct values

Issue: Migration Failures

Symptoms:

Migration failed
Table already exists

Solutions:

Check migration status
```
elizaos migrate status
```

Reset migrations

# WARNING: This will delete all data
elizaos migrate reset
elizaos migrate

Manual migration

# Run specific migration
elizaos migrate up

Plugin Development Issues

Issue: Plugin Not Loading

Symptoms:

Plugin appears in list but doesn't work
No error messages

Solutions:

Check plugin export

// Ensure proper export
export default myPlugin;

// Verify plugin structure
const myPlugin: Plugin = {
  name: 'my-plugin',
  version: '1.0.0',
  actions: [...],
  providers: [...],
  evaluators: [...]
};

Verify plugin registration

// Check plugin is added to runtime
const runtime = createRuntime({
  plugins: [myPlugin],
});

Check for naming conflicts

# Ensure unique plugin names
elizaos plugins list

Issue: Plugin Dependencies

Symptoms:

Cannot resolve module
Plugin dependencies not found

Solutions:

Install plugin dependencies
```
bun install plugin-dependencies
```

Check peer dependencies

{
  "peerDependencies": {
    "@elizaos/core": "^1.0.0"
  }
}

Verify plugin structure

# Check plugin directory structure
ls -la packages/plugin-name/

Testing Issues

Issue: Tests Failing

Symptoms:

Tests failed
Timeout errors

Solutions:

Run tests individually

# Run specific test
bun test __tests__/plugin.test.ts

# Run with verbose output
bun test --verbose

Check test environment

# Ensure test environment variables
cp .env.example .env.test

Increase test timeout

// In test file
describe("Plugin tests", () => {
  it("should work", async () => {
    // Test implementation
  }, 30000); // 30 second timeout
});

Debugging Tools

Enable Debug Logging

# Enable verbose logging
LOG_LEVEL=debug elizaos dev

# Enable Node.js debug
DEBUG=* elizaos dev

Use Development Tools

# Check TypeScript compilation
bun run type-check

# Lint code
bun run lint

# Format code
bun run format

Monitor System Resources

# Check system resources
htop
df -h

# Monitor network
netstat -tulpn

Getting Help

Information to Collect

Before seeking help, gather:

System information

node --version
bun --version
elizaos --version
uname -a

Error messages

# Copy full error output
# Include stack traces

Configuration files

# Share (without secrets):
# - package.json
# - tsconfig.json
# - .env.example

Where to Get Help

Documentation: Search these docs first
Discord: Join the ElizaOS Discord server
GitHub Issues: Report bugs or feature requests
Community Forums: Ask questions and share solutions

Creating Good Bug Reports

Include:

Clear description of the issue
Steps to reproduce
Expected vs actual behavior
System information
Relevant code snippets
Error messages and logs

Prevention Tips

Best Practices

Keep dependencies updated
```
bun update
```

Use version control

git init
git add .
git commit -m "Initial commit"

Test locally before deploying
```
bun run build
bun run test
```

Monitor application health

# Set up monitoring
# Check logs regularly

Backup important data

# Backup database
# Backup configuration

Development Workflow

Start with templates
Test changes incrementally
Use linting and formatting
Write tests for new features
Document your changes

This troubleshooting guide should help you resolve most common issues. If you encounter something not covered here, please contribute to the documentation or ask for help in the community!

Troubleshooting Guide

On this page