Skip to content

Troubleshooting

Jump to bottom
m4xx3d0ut edited this page May 13, 2026 · 3 revisions

Troubleshooting

Start every investigation with status:

workerbee doctor
workerbee mcp status
workerbee ingress status
workerbee projects

Use --json when sharing logs or debugging with an agent:

workerbee mcp status --json
workerbee ingress status --json

MCP Is Not Running

Start or restart:

workerbee mcp start
workerbee mcp restart

If the port is busy:

ss -lntup | grep ':8765'

Change the MCP port:

workerbee mcp restart --port 8876

Dashboard Certificate Is Not Trusted

Open the dashboard CA link after accepting the local dashboard warning, or export the CA:

https://dashboard.workerbee.localhost:19443/workerbee-ca.crt

workerbee ingress ca --output workerbee-ca.crt

Install system trust:

workerbee trust install --target system

Install browser NSS trust:

workerbee trust install --target nss

Check trust status:

workerbee trust status

On NixOS, system trust is declarative. Add the exported certificate to security.pki.certificates and rebuild, or use NSS trust for browser-only testing. If workerbee trust status reports certutil: null, run the NSS install from a shell with nssTools.

Chrome and Chromium can use either $HOME/.local/share/pki/nssdb or $HOME/.pki/nssdb. Install into both when debugging browser trust:

export CA=/tmp/workerbee-containerd-verify/global/caddy-local-root.crt

nix shell nixpkgs#nssTools -c bash -lc '
set -euo pipefail
pw="$(mktemp)"
: > "$pw"
trap "rm -f \"$pw\"" EXIT

for db in "$HOME/.local/share/pki/nssdb" "$HOME/.pki/nssdb"; do
  mkdir -p "$db"
  certutil -N -d "sql:$db" --empty-password 2>/dev/null || true
  certutil -D -d "sql:$db" -n "WorkerBee Caddy Local Root" 2>/dev/null || true
  certutil -A -d "sql:$db" -f "$pw" -t "C,," \
    -n "WorkerBee Caddy Local Root" \
    -i "$CA"
  certutil -L -d "sql:$db" -n "WorkerBee Caddy Local Root"
done
'

If certutil asks for Password or Pin for "NSS Certificate DB", it is asking for the existing user NSS DB password. For a dev-only host, back up and recreate the NSS DB directories if those stores contain only disposable dev certificates. Fully quit Chrome or Chromium after changing NSS trust:

pkill -f 'chrome|chromium' || true

CA Export Fails

The CA exists after WorkerBee Caddy has started and exported its local root:

workerbee mcp restart
workerbee mcp status
workerbee ingress ca --output workerbee-ca.crt

If it still fails, inspect:

workerbee ingress status --json

Look for ca_ready, ca_bundle, probe_error, and runtime probe details.

Dashboard CA Link Is Missing or 404

Restart MCP so the global ingress metadata and dashboard server are generated by the current WorkerBee build:

workerbee mcp restart
workerbee ingress status --json

The JSON should include dashboard_ca_download_url, dashboard_ca_sha256_url, ca_ready, and ca_bundle. If ca_ready is false, wait for Caddy startup to finish or inspect the runtime probe fields. In LAN mode, ca_download_url is the separate plain HTTP URL for other devices; it is normal for that field to be empty in loopback mode.

Dashboard Project Actions Are Inconsistent

Use the action scope to narrow the problem:

  • Row Start, Stop, and Delete target only that row.
  • Start Selected, Stop Selected, and Delete Selected require checked projects.
  • Start All, Stop All, and Delete All intentionally ignore checked projects.

If top-row buttons stay disabled or do not reflect the current selection, refresh the dashboard and inspect the recent action jobs in the Controls section. A queued or running job disables project actions until the job completes or falls out of the dashboard job list. If the issue persists, capture:

workerbee projects --json
workerbee mcp status --json
workerbee ingress status --json

LAN Device Cannot Resolve WorkerBee Names

Check WorkerBee DNS:

workerbee mcp status
workerbee ingress status --json

Confirm the client device DNS server is set to the WorkerBee host LAN IP. If using a custom DNS port, verify the client supports custom DNS ports.

If DNS port 53 is busy on the WorkerBee host:

sudo ss -lntup | grep ':53'

Either free the port for the test window, bind WorkerBee DNS to a specific LAN IP, or use a custom port for clients that support it.

LAN Device Resolves but HTTPS Fails

Check:

  • The LAN device installed the WorkerBee CA.
  • The hostname uses the active base domain from workerbee mcp status.
  • Host firewall allows 19443/tcp.
  • Runtime port publishing is active.
  • The project stack is running.

Commands:

workerbee projects
workerbee ingress status
workerbee mcp status

Project Is Stopped

If status reports PROJECT_STOPPED, change mode:

workerbee project mode lazy
workerbee project mode start

Then start or deploy again.

Control Plane Running but No App Workload Deployed

If project status says the control plane is running but no app workload is deployed, continue the manifest workflow instead of stopping after MCP or project start:

workerbee manifest prepare --name app --template frontend-api-store
workerbee manifest validate --stage app
workerbee manifest deploy-local --stage app

For existing stages, skip prepare and validate/deploy the stage you already have.

Degraded or Orphaned Workloads

Inspect detailed app status:

workerbee project status --json
workerbee logs <app>

If status reports orphaned workloads that are absent from the current stage, prune them with an explicit deploy:

workerbee manifest deploy-local --stage app --prune

Use prune only after confirming the stale workloads should no longer exist.

Kubernetes Manifest Validation Fails

WorkerBee local Kubernetes apply supports one workload per file with optional Service or Ingress documents. Multi-container pods and initContainers are rejected because local apply maps one pod container to one k1s workload.

Split sidecars, workers, and initialization into separate workload manifests for local WorkerBee deploys. If validation warns about Kubernetes command/args entrypoint semantics, verify the image entrypoint before relying on shell command overrides.

Logs for Failed Jobs

Start with normal logs:

workerbee logs <app> --tail 100

When no running container exists, WorkerBee falls back to matching exited containers by default. Use --no-include-exited only when you want to ignore exited containers.

Runtime Resources Are Stale

Inspect first:

workerbee cleanup

Execute cleanup:

workerbee cleanup --execute

If images are stale too:

workerbee cleanup --execute --purge-images

Direct Containerd Fails

Check privilege state:

workerbee --runtime containerd containerd-privilege status

Try the helper strategy:

workerbee --runtime containerd --containerd-privilege sudo-helper profile list

Stop the helper after the session:

workerbee --runtime containerd containerd-privilege stop-helper

If direct containerd is not required for the task, switch back to Podman or Docker for normal app validation.

Clone this wiki locally