Troubleshooting

Practical troubleshooting for bootstrap, module loading, Fleet verification, DNS, web-server validation and tmux sessions.

Bootstrap Does not Start

• Confirm the host can reach the repository or configured mirror over HTTPS.
• Run the downloaded script with bash and the intended setup action.
• Confirm the session has root privileges.
• Review /var/log/one-click/one-click-error.log where available.

Module Download Fails

If a valid cache exists, the loader can continue with it when mirrors are unavailable. If both primary/backup retrieval and the cache are missing, the module cannot be loaded.

SSH Disconnected

tmux attach -t one-click

Fleet Node Missing or Unreachable

1. Check that the node exists in the controller inventory/ledger.
2. Verify controller-to-node SSH reachability.
3. Run one-click fleet verify.
4. Repair trust/inventory before attempting distributed tasks.

Web-server Workflow Fails Validation

Inspect the generated virtual host and run the native NGINX/Apache configuration test before reload. Correct the underlying configuration instead of bypassing validation.

Cloudflare/DNS Operation Rejected

Confirm the API token is scoped to the intended account/zone and has the required DNS permissions. Do not switch to an account-wide token simply to bypass a permissions error.

Node.js Service Runs but the Site Fails to Load

Check the configured application port, HTTP health endpoint, startup command, virtual-host proxy and TLS response. See Node.js Applications for management options.

Network Repair Has No Suitable Recovery Set

A current system health check does not create an earlier known-good configuration. Save a versioned backup before making changes. For a disconnected remote VPS, prefer provider console access; see Network Repair.