Skip to main content
zmeel doctor checks every part of your Zmeel setup and reports pass, warning, or failure for each item. With --repair, it attempts to fix issues that can be resolved automatically. zmeel run calls doctor automatically before starting the server, so you only need to run it manually when troubleshooting or after changing configuration.

​
Usage

zmeel doctor
zmeel doctor --repair
zmeel doctor --repair --yes

​
Options

​
--repair
boolean
Attempt to repair fixable issues automatically. For each repairable failure, doctor prompts you to confirm before making changes (unless --yes is also set).
​
-y, --yes
boolean
Skip confirmation prompts during repair. Combine with --repair to repair all fixable issues without interaction.
​
-c, --config
string
Path to the config file. Defaults to ~/.zmeel/instances/default/config.json.
​
-d, --data-dir
string
Data directory root. Isolates all state from ~/.zmeel.

​
Checks

Doctor runs the following checks in order. A config file must be present and readable before the remaining checks can run.
CheckWhat it verifies
Config fileConfig file exists and can be parsed
Deployment/auth modeDeployment mode and auth settings are consistent
Agent JWT secretZMEEL_AGENT_JWT_SECRET is set or can be generated
Secrets adapterSecrets provider is accessible and the key file exists
StorageStorage directory exists or S3 bucket is reachable
DatabaseDatabase is reachable and migrations are up to date
LLM providerAPI key is present (warning only if missing, not a hard failure)
Log directoryLog directory exists and is writable
PortThe configured port is available

​
Examples

# Check your setup and report any issues
zmeel doctor

# Check and repair fixable issues (prompts for each repair)
zmeel doctor --repair

# Check and repair all fixable issues without prompting
zmeel doctor --repair --yes

​
Reading the output

Each check prints a status indicator:
  • ✓ — passed
  • ! — warning (non-blocking)
  • ✗ — failed (blocking if starting the server)
A summary at the end shows the total counts. If any checks fail, zmeel doctor exits with a non-zero status and zmeel run will not start the server.
Run zmeel doctor after changing your configuration with zmeel configure. It catches misconfigurations — like a wrong database URL or missing LLM key — before you start the server.

​
Alias

--fix is an alias for --repair: 
zmeel doctor --fix