Troubleshooting

Most failures come from one of these areas:

1. app launch
2. provider setup
3. voice setup
4. connector credentials
5. remote URL or token configuration

Eliza will not open

macOS

Re-download from the official GitHub releases page if Gatekeeper or notarization warnings look suspicious.

Windows

If SmartScreen appears, use More info and confirm you downloaded the official installer.

Linux

If the AppImage will not start:

chmod +x Eliza.AppImage

The first message hangs

Check:

• the API key is valid and has remaining credits
• whether Ollama is running (if using local models): curl http://127.0.0.1:11434/api/tags
• whether the selected model exists on the provider
• whether a remote backend owns provider routing (deploymentTarget in config)
• logs for specific errors: check ~/.eliza/logs/ or run eliza doctor

Voice is silent

Test voice preview first.

• if preview fails, fix the voice provider or audio output
• if preview works but replies stay silent, fix the speech provider
• if talk mode fails, check microphone permissions

A connector does not reply

Discord

• token wrong
• Message Content Intent disabled
• missing channel permissions

Telegram

• token wrong
• connector offline
• privacy mode blocking group behavior

Slack

• missing appToken for Socket Mode
• wrong signingSecret for HTTP mode

WhatsApp

• QR code not scanned or session expired
• authDir not set or not writable

Signal

• signal-cli not running or unreachable at httpUrl

General

For any connector: check the token/credential, confirm the connector is enabled in config (connectors.<name>.enabled is not false), and check logs for startup errors.

Guides:

• Connect Discord
• Connect Telegram
• All connectors

Remote connection fails

Check:

• the URL
• the token
• whether the backend is running
• whether the backend listens outside localhost
• whether the current device can reach that network

Useful chat commands

These commands work in the chat input and can help diagnose issues:

• /model — check or switch the active model
• /clear — clear the chat and start fresh
• /help — list available commands

See Chat Commands for the full reference.

Eliza is slow

• slow before the first token: choose a faster model or provider (Groq and Anthropic Haiku are fast options)
• slow throughout: check network limits or local model size (eliza-1-2b is faster than eliza-1-9b)
• check if fallback models are being used (slower providers may be engaged if the primary is rate-limited)
• for local models, ensure you have enough RAM for the model size

Start over

Quit Eliza, rename the state directory, and relaunch:

• macOS / Linux: ~/.eliza
• Windows: %USERPROFILE%\\.eliza\\

File a bug

Include:

• OS
• local, remote, or Eliza Cloud
• selected provider
• expected behavior
• actual behavior

Issue tracker: elizaOS/eliza issues