Troubleshooting

Each entry names a symptom you can observe, the cause the repository documents, and the fix. Start with the symptom, not the fix: several different failures produce a blank page or a failed start. If the manager has not been installed yet, the quick start is the better starting point.

Collect three facts: the exact command you ran, the last complete line of output, and which ports are listening. Most of the issues below are diagnosed by those three facts alone. On Windows, scripts/ports.ps1 lists the known ports with their owning process. On Linux and macOS, lsof -i tcp:<port> does the same.

Change one thing at a time. A configuration change, a process kill and a reinstall performed together leave you unable to say which one fixed or broke the situation.

The manager interface can be healthy while one project fails. In that case, read the project's overview and its service logs before touching the manager. A failed start usually names a missing path, a port conflict or a Docker problem. The logs guide explains where to look, and the projects guide explains the preflight checks.

Do not run the manager as root to get past a Docker permission error. Do not regenerate the vault key to fix a login problem. Do not delete the manager database before you have copied it aside. Do not edit the database by hand to change a project path; re-register the project instead. Each of these turns a recoverable problem into a data-loss problem.

The manager writes its proxy and denial logs to the platform log directory, and the launcher aggregates backend and web output into a log file in the product folder. A denial entry names the entry point and the reason; a launcher entry names the process and its output. Reading the right log is usually faster than restarting the stack and hoping the problem reproduces.

If the manager will not start at all, the first useful fact is whether the process exited or is still running without a listener. An exit with an error is a configuration problem; a live process with no listener is usually a port or process problem.

Write down the command, the output and the fix. The same machine tends to produce the same failures, and a short note saves the next investigation. If a fix requires changing a port or domain, record which clients were updated as well; a stale client is the most common follow-up failure.

If the symptom is not in the list, reproduce it once with the narrowest command and collect the last complete line of output. Then check the project's own logs before the manager's: a project that fails to start is usually explaining itself in its service log. The feature pages for projects, logs and configuration describe the normal behaviour those logs are diverging from.