Reference and troubleshooting

Check configuration, Docker access and data freshness in that order.

Option order

monit-docker -c ./monit-docker.yml --name 'web*' stats --output json
monit-docker cron --help
monit-docker serve --help

-c, --client, --name, --image, --label, --id and --ctn-group are global options. --interval, --state-file and rules follow their subcommand.

Useful exit codes

Code	Meaning
0	Completed successfully
2	Invalid arguments
110	Invalid configuration or command
114	No selected containers
115	Incomplete collection
116	Action failure
117	State lock already held
118	Invalid or inaccessible state
170 / 180	Docker connection or API error

monit --rsc status has its own status codes: 0 for running, 50 for exited. Do not interpret these as execution codes for other commands.

Quick diagnosis

Run check-config with your aliases and rules.
Check docker ps -a as the account running the agent. A remote Docker CLI context does not imply that the Python client uses the same connection.
Run stats --output json with the same selectors.
Inspect /v1/status, /readyz and logs. HTTP 503 means not ready, not necessarily that the HTTP server stopped.
Check state directory permissions and the process holding its lock.

Common pitfalls

No container metrics: nothing matches, collection failed or the snapshot is stale. Prometheus cannot reach localhost: inside another container, localhost refers to that container; use the agent’s Compose service name.

A rule is waiting: inspect cooldown and trigger-after. Changing the rule, container or timing parameters resets observation. State schema 2 used for trigger-after cannot be read by older versions (code 118).

Uncertain manual action: inspect its result before retrying. An accepted request or network timeout does not prove the Docker action completed.

When reporting an issue, include version, a redacted command, exit code and relevant logs. Remove tokens, passwords and webhooks.