Doctor and troubleshooting

Run doctor in the same project/template context as the affected services:

hum storefront all-services doctor

Doctor checks configuration requirements and reconciles runtime information. It distinguishes a listener managed by the expected service, a foreign process occupying the port, and stale registry state.

Configuration errors

Validate the selected registry, project, and template:

hum storefront all-services config validate

Check paths relative to the configuration file, repository-relative service working directories, required commands and files, dependency references, and environment variables.

A service will not start

Inspect status and retained output:

hum storefront all-services status
hum storefront all-services logs api --lines 200

hum rolls back services created by a failed multi-service start but leaves previously running services alone. Resolve the failed requirement, port, or health check and run start again.

Stale or externally changed processes

Every command reconciles the registry with the operating system and verifies process identity before signaling. The TUI performs the same reconciliation in the background. Use doctor for explicit ownership and stale-entry diagnostics rather than deleting state files manually.