Troubleshooting¶
The page says "No build yet"¶
The page shows "no colcon build logs found under …/log" when the workspace has no build logs.
- If the workspace was never built, run
colcon buildin it. The page shows the build as soon as colcon writes its first log. - If colcon writes its logs to another directory (
--log-base, or theCOLCON_LOG_PATHvariable), the dashboard does not find them. It reads the same log directory in every workspace:log, or thelog_basevalue inconfig.ini. Setlog_baseto the directory that your builds use, relative to the workspace.
A workspace is missing from the picker¶
The picker scans the scan roots, and your home directory if you allowed it. The scan goes four directory levels down. It skips hidden directories and symbolic links.
- Paste the path of the workspace into the box of the picker, and press Enter.
- If the picker does not scan your home directory, click "Scan roots…" in the picker and set the check box on the row of your home directory.
- Or add the parent directory of the workspace as a scan root: click "Scan roots…" in the picker.
The app window stays at "Loading…"¶
An installed app brings its open window to the front on each launch, and it does not load the page again. A page whose scripts did not start (for example in the middle of an upgrade) reloads by itself once after 8 seconds, and a new launch also reloads it. If it still does not start, it says "The page did not start" and shows a Reload button. In the app window, Ctrl+R always loads the page again.
The page says "The page did not start"¶
The scripts of the page did not load. The page then shows the error, and the server writes it to its log as a page error: line:
An ad blocker can block a script of the page by its file name. If the page starts in a private window but not in a normal one, allow localhost:8642 in your ad blocker, and reload the page.
The page says "OFFLINE"¶
The server does not answer.
- If you use the service, start it with
colcon-dashboard --start-service. - Without the service, run
colcon-dashboardin a terminal.
Then reload the page.
I cannot find the address of the server¶
When port 8642 is taken, the server uses another port. To print the address of the running server, run:
The service does not start, or an upgrade does not show¶
Read the log of the service:
After an upgrade, the server restarts by itself when no build runs. If it still runs the old version, look for auto restart lines in the log of the service, or run colcon-dashboard --restart-service. If you installed the dashboard again from another place (apt, pipx, or a virtual environment), run colcon-dashboard --install-service again, so that the service runs the new install.
The bell shows a warning¶
If the page runs on the same machine as the server, the server shows the notifications through notify-send (the libnotify-bin package) or gdbus. Click test next to the notification choice in the settings to send one. If none arrives, make sure that notify-send test shows a notification in a terminal.
On another machine, the browser shows the notifications, and it can block them. Hold the mouse over the bell to read the reason.
- Browsers allow notifications only on
localhostand onhttpsaddresses. A LAN address such ashttp://192.168.1.10:8642/does not work. Use an SSH tunnel and open the page throughlocalhost. - If you denied the permission before, allow notifications for the page in the site settings of your browser.
For notifications without an open page, set a notification command.
There is no "Ask Claude" button¶
The button shows only when the server finds the claude CLI. The server looks in PATH, then in ~/.local/bin. The systemd service has a short PATH, so it can miss a claude that your shell finds. Set the full path in config.ini, and restart the service:
The server answers "403 unknown Host header"¶
The server accepts only these addresses: an IP address, localhost, and the host name of the machine. This check stops other web sites from reading your logs. If you reach the server through another name, use its IP address, or use an SSH tunnel and localhost.