Troubleshooting

First diagnosis

Run project commands from the project directory. doctor checks local tools, Docker and gateway state, plus configured HTTP routes in the loaded project. The environment should be running for route checks; a stopped project may be reported as unreachable.

• Note the failed command and first concrete diagnostic.
• Check prerequisites before startup and runtime status after startup separately.
• Address one specific cause and check again.

dwell doctor

Check before startup

plan up shows planned actions and observed blockers without creating files or starting services. Address reported prerequisites before your next dwell up.

dwell plan up

A successful plan reserves no ports and guarantees no later successful startup. It does not cover every runtime or application failure.

Status and logs

ps shows roles, processes, Compose status and URLs including LAN status. logs lists available Dwell logs; without those logs, backend projects may show Compose output. Then select the log relevant to your failure.

dwell ps

dwell logs

Examples include dwell logs build, dwell logs compose, dwell logs frontend and dwell logs gateway. Targeted Dwell logs follow output and require the local tail utility. Stop following with Ctrl+C. Logs may contain application secrets; review before sharing.

Docker is not running

Symptom: Startup reports an unreachable Docker daemon or missing Compose prerequisites.

First check that Docker Desktop or Docker Engine is running. Use Linux containers; frontend-only projects also need Docker for the shared gateway.

dwell doctor

Address the Docker/Compose issues reported by doctor, repeat plan up and then start with dwell up.

A port is occupied

Symptom: The gateway or frontend cannot bind a port, or the printed URL contains a higher port.

Check the port finding with plan up. If only port 80 is occupied, Dwell can use an available high gateway port; that is not automatically a failure. Use the printed URL.

dwell plan up

For an actual conflict, identify the process occupying the port and decide deliberately whether it can be stopped. Read dwell logs frontend for frontend conflicts and dwell logs gateway for gateway issues.

Frontend fails to start

Symptom: The backend or gateway runs, but the frontend process fails to start or exits immediately.

Inspect ps and the frontend log: dependencies, Node version, start command and application errors are common causes. A custom frontend needs a valid configured start command.

dwell logs frontend

Address the concrete frontend error. Use dwell build to prepare dependencies and then dwell up; do not change framework versions on a guess.

Domain is unreachable

Symptom: The local .localhost address is unreachable or shows an unexpected page.

Check that the project runs with ps and inspect its configured URL including the port with access. routing list shows host and path; access alone does not check reachability.

dwell logs gateway

Check the configured route with doctor and read the gateway log. Custom domains outside .localhost need your own name resolution. After a physical project move, use reinit as described in the workflows guide.

HTTPS is not trusted

Symptom: HTTP works but the browser does not trust the HTTPS certificate.

Check the hostname, reported HTTPS status and trust in the mkcert CA on that specific device. doctor shows mkcert and gateway information; its HTTP route checks do not establish certificate trust.

dwell doctor

Configure certificate trust using the mkcert instructions linked in the network guide. It is a separate step on another device. Do not replace trust validation with permanently ignoring browser warnings.

LAN is unreachable

Symptom: The application works locally, but a phone cannot reach its .local address.

Check LAN status and the printed address with ps. Host and client need a shared reachable network and mDNS support.

dwell ps

Use the network guide to check interface selection, firewall, VPN and Wi-Fi isolation. up may succeed locally while reporting LAN failures separately; always test on the actual client.

Incompatible Node, PHP or stack

Symptom: Dwell reports an unsupported Node version, PHP version or stack combination.

Inspect your installed Node version and project configuration. versions list shows supported lines and compatible PHP versions. A frontend may require more recent Node than the CLI itself.

dwell versions list

Compare configuration and local prerequisites with the stack guide. Stack changes are not framework upgrades and do not migrate your application code.

Notes & limits

doctor and plan assist diagnosis; they are not complete application checks. doctor --repair changes gateway/registry state and is for a relevant state problem, not the first step for every issue. Do not delete volumes or secrets as a general repair. Let project-changing commands finish before starting another.

Next steps

The projects guide explains the normal lifecycle. Routing and networking cover specific URL and sharing issues.

Technical reference