Navigation
ELOWEN · Documentation

Last updated: October 27, 2026

Browse documentation · Troubleshoot the server and services
Operations and updates

Troubleshoot the server and services

Find your symptom below, check the likely cause, and follow the numbered steps. This article covers the installation; for the message a person in the browser sees, start with When something does not work.

Nothing works and you need a health check

Why: one command reports whether the daemon, providers, memory and plugins are ready.

  1. Start the daemon if it is stopped: elowen up.
  2. Run elowen doctor; a script can pass an existing token instead: ELOWEN_TOKEN='…' elowen doctor.
  3. Without a saved CLI sign-in it asks for an administrator username and password; without a terminal it prints what to run instead.

Tip: With two-step verification, approve the CLI sign-in in the browser. elowen setup runs the same checks.

A service is down

Why: the daemon runs the API, conversations, storage, plugins and background work; the web service serves the app.

  1. Run elowen status.
  2. Start or restart them with elowen up or elowen restart all.
  3. elowen down stops both and waits for active work to settle; --force stops that work at once.
  4. On a systemd host, read the units and their 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 right after it starts

Why: a port conflict, an old Node.js, mismatched backups, or a source build without its web build.

  1. Check the ports, the Node.js version and the log:
ss -ltnp | grep -E ':(4400|4500)\b'
node --version
journalctl -u elowen-daemon -n 100 --no-pager
  1. Free the port if another process holds it.
  2. Move to Node.js 22.19.0 or later.
  3. Restore the database and its plugin-secrets.key from the same backup.
  4. Build the web app for a source checkout.

A reply never arrives

Why: the turn may wait for an answer, a provider may fail, or the context may be full.

  1. Run elowen doctor and elowen status.
  2. /stats in chat shows the model, usage and context; /context in the CLI breaks the context down.
  3. The daemon log can name provider errors, rate limits, expired credentials and recovery after an interruption.
  4. Answer a waiting question or approval on the same surface; scheduled jobs and delegated work cannot, though some channels settle prompts.
  5. /compact summarizes older messages; /new starts fresh.

A summary is not a verbatim copy, so keep lasting decisions in Memory.

A spinner can also mean the proxy or event stream is broken: check the browser console and the daemon log. Reconnecting shows one line, such as "Reconnecting 2/5 · next attempt in 2 s".

A tool or plugin is missing

Why: the plugin may be disabled, ungranted, or short of credentials.

  1. Open Settings → Plugins and confirm it is enabled.
  2. Confirm the account has the plugin grant.
  3. Complete its settings and credentials, then read Capabilities and Activity for a loading error.
  4. Run /tools to list active plugin tools and their owners; accounts can see their own commands and granted plugins.

An MCP server is managed from MCP: fix its address or command, then reconnect. A change can show as pending while work settles, so do not submit it twice; skill edits need no restart.

A tool or command is denied

Why: a permission rule denies it, or the work runs where nobody can approve.

  1. Open Account → Models and find Command permissions and Tool rules.
  2. Read that command's rules: each allows, asks or denies, and the last match wins.
  3. Change the denying rule, or add a more specific allow rule after it.
  4. /yolo in the CLI approves eligible questions for that session only; it never overrides a deny rule or strict unattended blocking.

Delegated work keeps its starting boundary, so account changes do not widen a running child. Read-only mode is a guardrail, not a sandbox.

Delegated work or a workflow fails

Why: a runner error can affect delegated work without stopping ordinary chat, and an interrupted workflow leaves unfinished steps.

  1. Open the delegated-work view in the parent conversation and read the daemon log.
  2. Check whether the child finished, is still running or was interrupted before you start the same task again.
  3. Resume the workflow with WorkflowResume; completed steps are not replayed.

A Project or directory is wrong

Why: a conversation runs in one Project and one working directory, and a Git worktree counts only when the conversation points at it.

  1. Confirm the selected Project in Projects.
  2. In the CLI, /project switches the conversation to another Project, and /cd reports or changes the terminal's own directory.
  3. Point the conversation at the worktree directory.

Delegated work inherits the caller's Project and directory; plan and read-only modes add limits but keep the Project boundary.

Memory or search returns nothing

Why: the memory may be missing or uncategorized, or no embedding model is configured.

  1. Confirm the memory exists and has a category; uncategorized memories are not normally recalled.
  2. In Settings → Models, confirm an embedding model is configured. Without one, search by meaning is unavailable, though keyword retrieval may still work.

Memory is private to an account unless it belongs to a shared Project pool, and only eligible Project members recall pool memories.

Documentation search (the DocsSearch tool and the Ask AI command in the palette) likewise matches by meaning and keyword, or by keyword alone without a model, and answers immediately because its index is built in the background.

Compaction changes the running context, not saved Memory.

A channel stays silent

Why: the plugin, its access rules or the platform route is blocking the message.

  1. Run elowen doctor, then open the channel plugin's settings.
  2. Check that the plugin is enabled and its credentials are valid.
  3. Check that the sender, server, chat or thread is allowed, and that the group-reply and mention settings are met.
  4. Check that the sender is linked or admitted under the plugin's rules.
  5. Behind a reverse proxy, route /hooks/ to the daemon; a working web app does not prove webhook routing.

Warning: Never paste provider tokens into chat or logs.

A disk warning appears

Why: the filesystem that holds Chetty's data and managed environments is 80% full.

  1. Read the current figures in the host rings under Settings → System.
  2. Free space on that filesystem; the warning clears once enough is available.
  3. The warning turns critical when less than 2 GiB and 5% of the space remain.

The app shows Licence required

Why: the daemon has no usable licence, so only the licence page answers.

  1. Read the reason the page names.
  2. Enter the key on the page, or run elowen licence activate.
  3. After an outage, restore internet access; the daemon checks in on its own and unlocks within minutes.

Warning: A damaged licence file stops the daemon and cannot be repaired with another key. Restore it from a backup of the same installation, and never delete it.

A clock far off real time can lock the installation too; keep it in sync. Licence and activation explains every reason and the fix for each.

The web app does not load

Why: the web service, its port, the daemon address or the proxy's streaming route is wrong.

  1. Run elowen status and read the web log:
elowen status
journalctl -u elowen-web -n 100 --no-pager
  1. Check the web port, ELOWEN_DAEMON_URL and the proxy streaming routes, then reload for current assets.
  2. After an update, confirm both services are active and the daemon answers:
systemctl is-active elowen-daemon elowen-web
curl -fsS http://127.0.0.1:4400/health

The daemon listens on localhost; do not expose port 4400 to the internet.

Compaction loses context or keeps failing

Why: a summary keeps the gist rather than every message, and automatic attempts stop after repeated failures.

  1. Keep decisions that must survive in Memory, or start a clean investigation with /new.
  2. If automatic compaction keeps failing, read the daemon log and check the account's Compaction model.
  3. Run /compact by hand; the Compaction failure limit stops automatic attempts after three failures in a row.

A conversation can also stop compacting when its context stays at or above the trigger after a summary; /compact still works, and a new conversation is the reliable fix.

You need the logs or the instance files

Why: settings, accounts and conversation history live in PostgreSQL, while instance files live in the instance folder.

  1. Read the locations from ELOWEN_DATABASE_URL, ELOWEN_INSTANCE_ROOT (default ~/.config/elowen) and ELOWEN_LOG_DIR.
  2. Look for these files:
~/.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/
  1. For temporary detail, set ELOWEN_LOG_LEVEL=debug, then restore info.

The database is not the whole installation: back up the configuration directory, and keep the database with its matching plugin-secrets.key.

An update fails or a new version will not start

Why: the updater checks the release against the licence, and migrations run when a newer version starts.

  1. Run elowen update, and after an interruption run elowen update --recover before trying another update.
  2. Keep the logs and restore your backup when a newer version will not start; never delete migration or lock files.

Recover an interrupted update explains what the recovery command does and how a refused or failed update is resolved.

You want to reset or recover state

Why: different problems need different resets, and a full reset destroys saved data.

  1. Start a new conversation with /new, or empty the current one with /clear.
  2. Remove memories or categories from the Memory page.
  3. Run elowen setup to fill in missing configuration.
  4. Before a full reset, stop Chetty and make a verified backup.

Warning: The database and the instance folder with its plugin-secrets.key belong together: back them up and restore them as a pair. Removing the instance folder or dropping the database destroys saved data. Logs stay in the instance folder, or in ELOWEN_LOG_DIR when it is set.