Repository navigation
Troubleshooting
C-F0x edited this page Oct 26, 2026
·
1 revision
This guide lists common error scenarios, their root causes, and explicit remediation steps.
-
Symptom:
cgw clients testor a task fails reporting host key mismatch. - Root Cause: Trust On First Use (TOFU) recorded a fingerprint on initial connection. Rebuilding a VM, reinstalling the target OS, or changing SSH host keys altered the server's public key.
-
Fix:
- Inspect the presented key in the error message or WebUI dialog.
- Trust the new key explicitly:
cgw clients hostkey <clientId> --trust <SHA256:...>
- Or forget the old fingerprint to re-prompt on next connection:
cgw clients hostkey <clientId> --forget
- Symptom: Daemon reports that encrypted PEM with AES-CBC is not supported.
-
Root Cause: Legacy OpenSSL PEM encryption (
EVP_BytesToKeywith AES-CBC) is intentionally unsupported. -
Fix: Convert the private key to standard PKCS#8 format using OpenSSL:
openssl pkcs8 -topk8 -v2 aes-256-cbc -in old.key -out new.key
- Symptom: First build on a newly registered project fails immediately at the first step.
-
Root Cause: A
buildtask performs only the remote build; it intentionally does not auto-push source code. -
Fix:
- Push source code first:
cgw push <project> --wait
- Or use the recommended
push-build-pullworkflow preset:cgw workflows apply <project> push-build-pull --apply --run --wait
- Push source code first:
- Symptom: Shell script or Gradle wrapper fails on remote Unix host.
-
Root Cause: Windows CRLF (
\r\n) line endings in executable scripts. -
Fix: CompileGateway automatically normalizes scripts containing a shebang (
#!) to LF onpush. If you passed--keep-crlf, remove that flag and re-push:cgw push <project> --wait
-
Symptom: Build steps all exited with code 0, but the job status is marked
failedwith codeartifactMissing. -
Root Cause: The manifest or task declared an expected output file or directory (
artifactPathoroutputs), but the remote build did not generate a file at that path. -
Fix:
- Inspect the actual remote output paths using
cgw tree <project> build --side remote. - Adjust the
artifactPathorvariablesin your task/manifest to match the real output location.
- Inspect the actual remote output paths using
-
Symptom: Starting a task or batch fails with HTTP 409
projectBusy. - Root Cause: The project already has an active or pending job holding the project-level lock.
-
Fix:
- Wait for the active job to finish, or inspect it:
cgw doctor cgw jobs - Queue the request in the per-project FIFO:
cgw run <project> <task> --enqueue cgw batch run <project> <batch> --enqueue
- Or cancel the stuck job:
cgw jobs cancel <jobId>
- Wait for the active job to finish, or inspect it:
-
Symptom: Starting a task fails with HTTP 409
hostBusy. -
Root Cause: Global
hostLockis enabled inconfig.json, and another project is currently executing a job on the same SSH client. -
Fix: Use
--enqueueto wait for the host to free up, or disablehostLockif parallel builds on that machine are safe:cgw set host-lock off
- Symptom: Daemon fails to start, logging that port binding failed.
-
Root Cause: A fixed
portinconfig.jsonis occupied by another process. -
Fix:
- Edit
config.jsonand set"port": 0to let the system select an available port automatically, or assign a different unused port number.
- Edit
- Symptom: Log warns that default MCP port 3994 is occupied.
-
Behavior: Daemon automatically falls back to an available dynamic port. Inspect the actual active URL with:
cgw mcp url
-
Symptom: Browsing directories or registering a project returns 403
outsideRoot. -
Root Cause: The requested host path is outside the user home directory and not included in
allowedRoots. -
Fix: Add the host directory to the whitelist:
cgw set roots add "D:/MyProjects"
- Symptom: Repeated login attempts return HTTP 429.
-
Root Cause: Login protection enforces a cooldown interval per IP (
loginIntervalSeconds). -
Fix: Wait for the
retryAfterSecondsduration returned in the error response before retrying.
-
Rule: CompileGateway credentials can only be modified from the local loopback interface (
127.0.0.1/::1), which is always exempt from authentication. -
Fix: Log in directly on the machine running the daemon and update the credentials:
cgw set user alice
← Home