Troubleshooting

Start with three commands. make doctor checks the settings and the connections to Home Assistant and the store, make logs (or make run in the foreground) shows what Stewart says, and make status shows each app’s state and last failure. Most problems name themselves in one of them. On a Git or image server, which has no Makefile, use docker compose -f compose.git.yaml logs -f stewart and … exec stewart stewart status instead.

Stewart does not start

The child config "token" under "stewart.home_assistant" must be configured. .env has no token, or there is no .env. Run make env, then fill in the token. See Install Stewart.

… is not a Stewart setting. An environment variable starting with STEWART_ has a typo, or one underscore where two belong. See Configuration.

The store is unreachable. With persistence.url set, Stewart checks the store at start. Check that the valkey container runs (docker compose ps); it starts only while .env sets COMPOSE_PROFILES=store.

STEWART_CONTROL__TOKEN is missing. The control socket needs a token. make env creates .env with one; on an older .env, add STEWART_CONTROL__TOKEN= followed by openssl rand -hex 16.

Stewart cannot reach Home Assistant

It keeps reconnecting. Check the URL from inside the container: make sh, then wget -qO- http://your-host:8123. localhost is the container itself; use Home Assistant’s host name or IP, or host.docker.internal when it runs on the same machine.

AdministratorRequired. The token belongs to a user without administrator rights.

It worked, then stopped after a restart of Home Assistant. Stewart reconnects on its own, waiting up to a minute between tries (reconnect.max_delay). make status shows the connection on its first table.

An app does not start

make status shows the app as failed, with the reason; the log has the full message.

Message	Fix
… matches no parameter of …::__construct()	An option in stewart.yaml has a name the constructor does not have
needs option "…"	Set the option, or give the parameter a default
Persistence is not configured	Set STEWART_PERSISTENCE__URL
MQTT is not configured	Set STEWART_MQTT__URL
A … schedule needs a location	Set a location in Home Assistant under Settings → System → General
… is not a generated … entity	Fix the entity ID, or run make generate

The app is not listed at all. The class must be in apps/, implement App, and carry #[Automation]. The log warns about a class without the attribute, and about a file that fails to load.

The error reference lists every message.

An app does not react

1. Check the app runs: make status shows it as running, not paused or failed.
2. Look at its subscriptions: make status APP=<app-id> lists each one with how many events it received and handled.
   • Nothing received: the entity ID or the event type does not match. Check it under Developer tools → States in Home Assistant.
   • Received but not handled: an operator stopped the events. whenChangedTo('on') ignores changes from unavailable, and a first state is not a change. A filter() before a time window can hide the change the window needs; see Put time windows first.
3. Trace it: make run TRACE=<app-id> (or make watch TRACE=…) logs each event the app receives, each call of its handler and each service call. See Tracing an app.
4. Write a test that pushes the state you expect; it shows whether the app or the input is wrong.

Service calls fail

was rejected by Home Assistant. Try the same call under Developer tools → Actions; Home Assistant’s reason is in the message.

could not reach Home Assistant. Stewart was reconnecting at that moment.

was refused. Too many calls waited for an answer at once. Call one service with several targets instead of one call per entity.

The call succeeds but nothing happens. Dry run may be on: the log says service_calls.dry_run is on. Remove DRY_RUN=1 or STEWART_SERVICE_CALLS__DRY_RUN.

Apps are slow, or events are dropped

… dropped … warnings naming a worker. A handler blocks the worker, so events pile up. Look for sleep(), a slow HTTP request, or a long loop, and replace it with a schedule, a wait, or a non-blocking client.

A worker restarts again and again, then stays down. After too many restarts in a minute, Stewart stops the worker (quarantined in make status). Fix the cause in the log, then run docker compose exec stewart stewart worker:restart <number>.

Exposed entities

ComponentMissing. The Stewart integration is not installed in Home Assistant, or Home Assistant was not restarted after installing it. See Exposed entities.

ProtocolMismatch. Stewart and the integration have different versions.

Deploying

A pushed commit does not go live. In Git mode, a commit that fails stewart check is rejected and the old one keeps running. make status shows it on the deploy row; the log says why.

make watch does not reload after a save. It watches only the directories the autoload section of composer.json names, services.php and stewart.yaml, and reloads about two seconds after the last change. A file outside those, such as a test, or a .env change, needs make run again.

A reload changed nothing. The reload row in make status says failed with the first error of the check, and the workers kept running the code they had. Run make check, fix what it names, and reload again. When it says partly applied, the settings it names wait for a restart; only apps and workers change on a reload.

make status cannot connect on Docker Desktop. macOS and Windows cannot share the control socket with the host. Run it inside the container instead: docker compose exec stewart stewart status.

Still stuck?

Open an issue at github.com/stewart-php/stewart with the log lines, make status, and the app’s code.