pve-agentsOperations
Troubleshooting
Common symptoms and the quickest safe fix.
Controller and access
| Symptom | Check |
|---|---|
| Stream connects but sends no updates | Exclude /api/workspaces/*/agent from proxy buffering and compression. See reverse proxy. |
| Sign-in succeeds but no session remains | Make CONTROLLER_URL exactly match the browser origin. |
| Health endpoint works but database requests fail after an update | Run pnpm db:migrate before starting the service. |
Nothing leaves requested | Run pnpm worker:tick or enable WORKER_ENABLED. |
| A CLI command cannot start | Run pnpm build so its CLI bundle exists. |
| The UI is an error page after deployment | Load the affected page in a browser; inspect client errors and verify deployed dependencies. |
Agents
| Symptom | Check |
|---|---|
| Launch form has no choices | Create and enable an agent in Settings → Agents. |
| API request fails validation | Include a configured agent's harnessId. See HTTP API. |
harness: this controller cannot run "<kind>" | Use a Type supported by this release, or update the controller. |
| Agent is unauthenticated | Correct the configured credential and launch a new workspace; running workspaces retain the old credential. |
Runner reports ERR_MODULE_NOT_FOUND | Rebuild the template with the supported build script, then launch a new workspace. |
Provisioning and template
| Symptom | Check |
|---|---|
destroy_ownership_mismatch | Stop and inspect the LXC. Its ownership marker does not match this controller. |
| First clone returns 403 | Grant VM.Audit and VM.Clone on the selected template VMID. |
Provisioning fails at addressed | Verify DHCP, the Proxmox bridge, and WORKSPACE_SUBNET. |
| Template says it has no DNS | Verify the scratch container's bridge, DHCP, and outbound network access. |
| Template reports a missing tool | Inspect the retained build container and confirm the tool is on the agent user's non-login PATH. |
Workspaces and reaping
A workspace will not reap when it is blocked, has uncommitted or unpushed work, or cannot be inspected. The timeline identifies the reason. Push or discard work, or destroy the workspace explicitly when appropriate.
An orphan after restoring the database is expected. The controller reports orphans but does not delete them automatically; inspect and remove them deliberately.
Last updated on