Troubleshooting

For plugin problems, start at Settings → Plugins → Installed; for denied tools, check Account → Models → Command permissions. If a service is down or a turn is stuck, use the CLI checks below to narrow it down.

Check whether Elowen is ready

Run the health and readiness check:

elowen doctor

The daemon must already be running. In a terminal, doctor uses the credential saved by elowen login; without one it asks for an administrator username and password, and an account protected by two-step verification approves the sign-in in the browser. Scripts can supply an existing token instead:

ELOWEN_TOKEN='…' elowen doctor

Without a terminal and without a token, doctor prints what to run instead of prompting.

If the daemon is stopped, start it with elowen up. Administrators can also read the same authenticated readiness report at GET /system/readiness.

A service is unavailable

The daemon runs the API, conversations, storage, plugins, and background work. The web service serves the browser app. Check both with:

elowen status

Start or restart services with elowen up or elowen restart all. To stop them, use elowen down; it waits for active work to settle. Use elowen down --force only when you intend to stop that work immediately.

For a systemd installation, inspect the service status and recent logs:

systemctl status elowen-daemon elowen-web
journalctl -u elowen-daemon -n 100 --no-pager
journalctl -u elowen-web -n 100 --no-pager

The daemon exits immediately

Check the ports, Node.js version, and daemon log:

ss -ltnp | grep -E ':(4400|4500)\b'
node --version
journalctl -u elowen-daemon -n 100 --no-pager

Common causes include another process using the configured port, an unsupported Node.js version (Elowen requires Node.js 22.19.0 or later), a database and plugin-secret key from different backups, or a source build missing its separate web build.

A turn does not answer

First check elowen doctor and elowen status. In chat, /stats shows model, usage, and context details; in the CLI, /context opens the context breakdown. The authenticated GET /brain/status endpoint reports the current conversation's live state, queued work, parked questions, and runtime diagnostics. The daemon log can identify provider errors, rate limits, expired credentials, or recovery after an interruption.

If a turn is waiting for a question or approval, respond on the same interactive surface. Scheduled jobs and delegated work cannot answer interactively. Supported channel plugins can present and settle some prompts in chat.

For an old or full context, use /compact to summarize older messages or /new to start a fresh conversation. Compaction is a summary, not a verbatim copy; save important lasting decisions in Memory. A browser spinner may also mean the reverse proxy or event stream is broken, so check the browser console and daemon log before retrying. While the app reconnects to the daemon it shows one short status line, such as "Reconnecting 2/5 · next attempt in 2 s".

A tool or plugin is missing

Check Settings → Plugins → Installed to make sure the plugin is enabled. Then confirm the account has the required plugin grant, the plugin's settings and credentials are complete, and its Capabilities and Activity views show no loading error.

In the CLI, administrators can run /tools to list the active plugin tools and the plugin that owns each one. Other users can check their available command list and granted plugins. An MCP server's connection is managed from MCP; after fixing its endpoint or command, reconnect it. Some MCP tools appear by name first and load their details only when needed.

Plugin changes can show as pending while active work settles. Do not submit the same change again: once the restart is queued, it will take effect when the daemon restarts. Skill edits apply from the next message without a restart.

A tool is denied

Review Account → Models → Command permissions. Rules can allow, ask, or deny a tool or command, and the last matching rule wins. /yolo affects eligible permission questions in the current CLI session only. It cannot override a deny rule or a block on unattended work.

Delegated work keeps the permission boundary it started with. Changing account settings does not widen a running child, and read-only mode is a guardrail rather than a filesystem sandbox.

Delegated work or a workflow failed

Check the delegated-work view in the parent conversation and the daemon log. A runner error can affect delegated work without stopping ordinary chat. Do not launch the same task again until you know whether the child completed, is still running, or was interrupted.

A workflow runs independent steps in parallel and waits for each step's dependencies. Use WorkflowResume after an interruption to retry unfinished steps; completed steps are not replayed.

A Project or directory is wrong

Confirm the selected Project in Projects. In the CLI, /project switches the conversation to another Project, and /cd reports and changes the terminal's own working directory. A Git worktree is an ordinary directory; a conversation can use it only when pointed to that directory.

Delegated work inherits the caller's Project and working directory. Plan and read-only modes add execution limits but do not replace the Project access boundary.

Memory or semantic search returns nothing

Check that the memory exists and is categorized. In Settings → Models, confirm an embedding model is configured. Without one, meaning-based search is unavailable; keyword retrieval may still work.

Documentation search (the DocsSearch tool and the palette's Ask AI) behaves the same way: it matches by meaning and by keyword together when a model is configured and by keyword alone without one, and it answers immediately rather than waiting for its index, because the documentation index is built and refreshed in the background.

Memory is private to an account unless it belongs to a shared Project pool. Only eligible Project members can recall shared-pool memories. Compaction changes the active conversation context, not saved Memory.

A channel integration is silent

Run elowen doctor, then check the channel plugin's settings and access rules:

• The plugin is enabled and its credentials are valid.
• The sender, server, chat, or thread is allowed.
• Group-reply and mention settings are satisfied.
• The sender is linked or admitted under the plugin's rules.

For a reverse-proxied webhook, route /hooks/ to the daemon. A working web app does not prove webhook routing is set up. Never paste provider tokens into chat or logs.

A host disk warning appears

Administrators get a warning when the filesystem that holds Elowen's data and managed environments is 80% full. The warning becomes critical when less than 2 GiB and 5% of the space remain. Free space on that filesystem. The alerts clear once enough space is available again. The current disk figures are shown in the host rings under Settings → System.

The app shows Licence required

The daemon has no usable licence: only the licence routes answer (GET /health, GET /setup, GET /licence, POST /licence/activate), everything else returns licence_locked. The page names the reason; the common fixes are:

• No licence installed — activate with elowen licence activate or enter the key on the page.
• Unreachable server past the grace period — restore the server's internet access; the daemon checks in on its own and unlocks within minutes when a licence is stored.
• Refused or wrong server — the licence was revoked, moved, or belongs to another installation ID. Contact support or activate the key meant for this server.
• Expired — renew the licence, then activate the new key.
• Corrupt licence.json — the daemon cannot boot and activation cannot repair the file. Restore it from a backup of the same installation, or contact support; never delete it.

A clock far off real time can also lock the installation; keep the server clock in sync. Full reference: Licence.

The web app does not load

Check the service status and web log:

elowen status
journalctl -u elowen-web -n 100 --no-pager

Then check the configured web port, ELOWEN_DAEMON_URL, reverse-proxy streaming routes, and whether the browser has current assets. The daemon listens on localhost by default; do not expose port 4400 directly to the internet.

After an update, verify that both services are active and the daemon health endpoint responds:

systemctl is-active elowen-daemon elowen-web
curl -fsS http://127.0.0.1:4400/health

Compaction loses context or keeps failing

Use /stats or /context to inspect usage; use /compact to request a summary. Summaries do not preserve every earlier message word for word. Store durable decisions in Memory, or use /new for a clean investigation.

If automatic compaction fails repeatedly, check the daemon log and the account's selected compaction model. The assistant's Compaction failure limit stops automatic attempts after three consecutive failures by default, while manual /compact stays available. A conversation can also stop compacting when its context still sits at or above the trigger after a summary; /compact still works there, and a new conversation is the reliable fix.

Find logs and persistent data

Settings, accounts and conversation history live in the PostgreSQL database that ELOWEN_DATABASE_URL points to. Instance files live in ELOWEN_INSTANCE_ROOT, by default ~/.config/elowen, and ELOWEN_LOG_DIR can override the log directory.

~/.config/elowen/licence.json
~/.config/elowen/plugin-secrets.key
~/.config/elowen/logs/daemon-YYYY-MM-DD.log
~/.config/elowen/logs/web-YYYY-MM-DD.log
~/.config/elowen/brain/
~/.config/elowen/plugins/
~/.config/elowen/plugins-data/
~/.config/elowen/plans/
~/.config/elowen/tool-results/

The database is not the whole installation. Back up the complete configuration directory when possible, and keep the database with its matching plugin-secrets.key. To collect more detail temporarily, set ELOWEN_LOG_LEVEL=debug, then restore info.

Updates, releases, and migrations

Update an installed instance with:

elowen update

This asks the licensing server for the latest core release covered by the installation's licence, downloads and verifies it, and installs it while Elowen keeps running; the managed services stop only briefly to switch packages and restart. There is no npm-based release channel. A refused check names the licence server's reason, usually a revoked licence. A source checkout can be newer than any released version, so Elowen does not replace it with a licensed release. Automatic updates are opt-in, under Settings → System.

If an update is interrupted, elowen update --recover removes staged files that were never swapped in, rolls back a swap that was interrupted before it was proven, or finishes publishing a commit that was proven. Run it before trying another update.

Database migrations run when the daemon starts a newer version. Make a recoverable backup before a version jump. If the daemon then fails to start, preserve the logs and inspect the journal before trying another update. Do not delete migration or lock files as a workaround.

Reset or recover state

• Start a new conversation with /new, or clear the current conversation with /clear.
• Remove individual memories or categories from the Memory page.
• Run elowen setup to fill in missing configuration.
• For a full reset, stop Elowen and make a verified backup first. Removing the instance folder or dropping the database destroys saved data. The database and the instance folder with its plugin-secrets.key belong together; back up and restore them as a pair. Logs stay in the instance folder, or in ELOWEN_LOG_DIR when it is set.

Next: Glossary