Skip to main content

​
Overview

The doctor command runs a suite of health checks to verify that a UseZombie component is correctly configured and can reach its dependencies. There are two modes: API mode and worker mode.

​
API mode

zombied doctor
Checks run in API mode:
CheckWhat it verifiesIf it fails
PostgreSQL connectionCan connect and run a query against the databaseVerify DATABASE_URL is correct. Check that PostgreSQL is running and reachable from this host.
Redis connectionCan connect and ping RedisVerify REDIS_URL is correct. Check that Redis is running and reachable.
Clerk configurationCLERK_SECRET_KEY is set and non-emptySet the variable in your .env or environment. Obtain the key from the Clerk dashboard.
Required env varsAll required API variables are presentSee Environment variables for the full list.
Port availabilityAPI port (default 3000) is not already boundStop the conflicting process or change PORT.
Metrics port availabilityMetrics port (default 9091) is not already boundStop the conflicting process or change METRICS_PORT.

​
Worker mode

zombied doctor worker
Runs all API-mode checks plus additional worker-specific checks:
CheckWhat it verifiesIf it fails
Executor socket/run/zombie/executor.sock exists and is connectableVerify zombied-executor.service is running: systemctl status zombied-executor.
Executor healthExecutor responds to healthCheck RPCRestart the executor: systemctl restart zombied-executor. Check executor logs for startup errors.
Sandbox backendSANDBOX_BACKEND is a recognized value (host or bubblewrap)Correct the value in .env.
GitHub App keyGitHub App private key is accessibleVerify the key file path or secret manager reference is valid. Re-download from GitHub App settings if needed.
Landlock supportKernel supports Landlock (Linux 5.13+)Upgrade the kernel or set SANDBOX_BACKEND=host for dev use.
cgroups v2cgroups v2 is mounted and writableVerify /sys/fs/cgroup is cgroups v2. Some older systems need systemd.unified_cgroup_hierarchy=1 on the kernel command line.

​
Example output

$ zombied doctor worker
[OK]   PostgreSQL connection
[OK]   Redis connection
[OK]   Clerk configuration
[OK]   Required env vars (6/6)
[OK]   Executor socket (/run/zombie/executor.sock)
[OK]   Executor health (responded in 2ms)
[OK]   Sandbox backend (bubblewrap)
[OK]   GitHub App key
[OK]   Landlock support (ABI v3)
[OK]   cgroups v2

All checks passed.

$ zombied doctor worker
[OK]   PostgreSQL connection
[OK]   Redis connection
[FAIL] Clerk configuration: CLERK_SECRET_KEY is empty
[OK]   Required env vars (5/6 — missing: CLERK_SECRET_KEY)
[OK]   Executor socket (/run/zombie/executor.sock)
[FAIL] Executor health: connection refused
[OK]   Sandbox backend (bubblewrap)
[OK]   GitHub App key
[OK]   Landlock support (ABI v3)
[OK]   cgroups v2

2 checks failed. Fix the issues above and re-run.

​
Exit codes

CodeMeaning
0All checks passed
1One or more checks failed