FAQ

Troubleshoot in this order: version first, then data source, then credentials and cache. If an error message contains passwords, sessions, Agent install commands, or third-party secrets, do not paste it into a public issue.

Find your scenario

Not sure which entry you need? Start from the symptom:

First deployment and access

Scenario	Entry
*.workers.dev does not open after deploying	About *.workers.dev access
404 after changing the admin path	404 after changing the admin path
The server cannot reach Cloudflare / Fastly / Akamai, so the Agent will not install	A node cannot reach Cloudflare / Fastly / Akamai
The installer rejects --token	Installer no longer accepts --token (1.1.65+)
BusyBox fails NQ/IP with setpriv argument errors	BusyBox nodes fail NQ/IP with setpriv argument errors

Node offline or not reporting

Scenario	Entry
Agent released, but the node version/state has not changed	Agent released but node version has not changed
An IPv6-only node cannot be probed	IPv6 and Cloudflare probes
An External Latency node stays "not yet reported"	External latency node shows "not yet reported"
Proxy checks stay offline or time out	Proxy checks stay offline or time out

Updates

Scenario	Entry
System update shows HTTP 429	System update shows HTTP 429
The panel shows a new version but nothing ever updates	The panel shows a new version but nothing ever updates
The instance lags — do nodes still update?	Nodes follow the official channel when the instance lags

Display, data and capacity

Scenario	Entry
NQ images missing or stale	NQ images missing or stale
Disk capacity numbers look wrong	Disk capacity display
Changing themes or using Canvas themes	Themes and Canvas themes
Is the free tier enough?	Free tier

Security, backup and integration

Scenario	Entry
Backing up and restoring data	Backup and restore
Browser CORS errors on the public API	Browser CORS errors on the public API

System update shows HTTP 429

The Worker hit an upstream rate limit reading the official GitHub Raw manifest; it is not an Agent failure. Since 1.0.38, update checks use a six-hour success cache, merged concurrent requests, and a 15-minute failure backoff. When the official source is unavailable, the last successful cache is used; cold start uses the trusted manifest bundled with the deployment.

• "Using current deployment version / cache result" is a safe degradation.
• Do not refresh repeatedly or raise retry frequency.
• Check /api/health, /update-manifest.json, and /bin/VERSION for the same version.
• Self-hosted updates run through the deployment repository's NIE-SLA Online Update workflow; no GitHub token input is needed.

About *.workers.dev access

Self-hosted deployments can use the *.workers.dev address by default — a fresh one-click deployment usually has no domain yet, so this is its main entry. After binding a custom domain, if you do not want to keep that parallel hostname (it would bypass your custom-domain rate limits and protections), add the text variable ALLOW_WORKERS_DEV = false under Worker → Settings → Variables and Secrets and save; the official production site additionally disables the workers.dev route at the configuration level. Also double-check the path: the public status page is / and the admin entry is your configured ADMIN_PATH (not /admin).

404 after changing the admin path

When ADMIN_PATH is saved, the old entry stops working immediately. Reopen "Worker URL + new path". The path is not authentication; the real boundary is the password, short session, and optional TOTP.

Agent released but node version has not changed

Agents poll the update policy; they do not all upgrade the moment a release is created. Check agent_version, online state, and Manager status in the admin panel, then on the node:

sudo cftz status
sudo cftz log 100

Very old versions may lack the current Manager or full verification chain; re-run the latest install command generated for that node. Do not reuse another node's command; its token is single-node.

BusyBox nodes fail NQ/IP with setpriv argument errors

1.0.49-1.0.50 passed GNU setpriv --reuid/--regid arguments to BusyBox; later direct privilege drop fixed startup but stripped NQ's raw-socket, latency, and route probing, producing "task succeeded but latency all 0, return route NoData". Upgrade to v1.0.58+: NQ and IP unlock run directly under the root-only Manager without nstatus-task, no_new_privs, or user namespaces. Metric collection still runs as the unprivileged nstatus service; the Manager accepts only the two fixed actions and enforces script SHA-256, private directories, no symlinks, fixed PATH, timeouts, and output limits.

v1.0.59 raised the NQ deep-check cap from 30 to 60 minutes so slow disks do not exit early during HardwareQuality; IP unlock stays at 10 minutes.

Since v1.0.64, NQ options (HardwareQuality y/f/v/n, IPQuality y/n, NetQuality y/l/n, Return Route y/n) are chosen per task in the admin UI, for single and batch runs; NQ tasks have no external timeout, and queue expiry keeps a 7-day grace.

v1.0.66 fixed batch NQ being killed by exit 124 at ~600 s on old Agents: the Worker re-issues a 3600-second compatibility cap for pre-v1.0.64 Agents; v1.0.64+ Agents still have no external timeout.

v1.0.67 fixed batch NQ/IP dialogs not closing after "confirm queue", missing toasts, and some VPSes not starting: batches now create tasks 5 at a time, the frontend closes the dialog immediately with a queued notice, and the batch request timeout rose to 60 s.

v1.1.0 moved to decimal versions (1.1.0): backup preview/restore gained low-frequency D1 rate limiting, and task timeouts now note "the request may still be running server-side, refresh later".

v1.1.1 added a force stop for NQ/IP unlock tasks: queued tasks are cancelled immediately, and the new Agent terminates the running task as a whole script process group after detecting the cancel flag; the table and detail dialog show a "Force stop" button and a "Stopping" state.

v1.1.2 made unlock info in the public status and admin panel prefer the NodeQuality report, so a fully unlocked NQ report is no longer overwritten by an older IP.Check.Place failure; 中国 renders in red, and locked/failed/member-only states appear in a red badge.

v1.1.3 fixed NQ component downloads on networks such as Tencent Cloud: the static script keeps the official GitHub source, falls back to tested mirrors when downloads fail, and enforces SHA-256. The Agent task Runner gained instance ownership and a 30-minute heartbeat fallback, and the duplicate /api/agent/tasks GET route was fixed.

v1.1.4 added the accelerator selector (auto / EdgeOne China / Cloudflare overseas) to the NQ dialog. The audited script prefers the public NIE-Proxy accelerator and falls back to official sources and mirrors; SHA-256 verification is unchanged.

v1.1.5 routes the Geekbench 5 packages downloaded inside HardwareQuality through the selected NIE-Proxy accelerator as well; the allowlist adds cdn.geekbench.com.

v1.1.6 removed EdgeOne from the NQ dialogs, leaving "Default" and "Cloudflare overseas"; historical eo tasks fall back to the default automatically.

v1.1.7 made the upload API authenticate before parsing the body. Its static budget test covered only baseline traffic; later production data showed that probes, Durable Objects, and scheduler duration were underestimated, so it must not be treated as a 100-node guarantee.

v1.1.8 fixed target IDs containing &: the Worker resolves original ID, normalized ID, and scanned match so metrics, pings, config, and location land on the original target.

v1.1.9 fixed occasional cross-chart updates when switching metric time ranges, made TCP Ping and Latency curves break on packet loss, and re-laid out the admin probe list.

v1.1.10 added an "Endpoint continuity" toggle to the chart toolbar: Latency and TCP Ping break at loss or failure by default, and the toggle connects across null values with the choice saved in the browser.

v1.1.11 restored the previous table layout for the admin probe list and removed the oversized monitor blocks and inline padding; information density and action layout return to the pre-1.1.8 shape.

v1.1.12 reduced the overall probe cadence: 3-second single timeouts, 2-minute status snapshots, 3-minute regional latency updates, and automatic 10-minute degradation for repeatedly failing targets. NQ report images use edge caching, Agent task cancel polling moved from a fixed 2 seconds to 5-10 second backoff, and D1 aggregate caching plus new indexes shipped.

v1.1.18 shipped the 300-second experience, WS reuse, hourly R2 buffering, and cache/304 support; v1.1.22 added the batch Ping API so a public panel can read the full VPS Ping history in one request. The target deployment's manifest and release record remain authoritative.

IPv6 and Cloudflare probes

"Agent online but CF latency failing" is usually a direction problem: Agent reporting only proves outbound network; whether Cloudflare can reach the port is a separate path. Key points:

• Enter IPv6 in the host field without []; put the port in the port field.
• Literal IPv6 may be rejected by Cloudflare; try a DNS-only AAAA domain for the same address.
• Do not enable the proxy (orange cloud): AAAA resolves to Cloudflare proxy addresses, and Workers TCP sockets forbid connecting to Cloudflare IPs.
• From another public IPv6, verify with nc -6 -vz domain port.

Full troubleshooting is in the IPv6 topic of this documentation.

NQ images missing or stale

• Network and Return Route images are rendered and uploaded by the Worker; on image-host failure the UI falls back to the text report and the task is not failed.
• Public image URLs are same-origin proxies; the upstream host is never exposed.
• The chain runs through the official public broker; ordinary deployments cannot and need not configure their own NQ_IMGBED_URL/NQ_IMGBED_TOKEN.
• Only reports produced after configuration takes effect are processed; old reports are not backfilled.

External latency node shows "not yet reported"

Creating the node record is not deployment. Check: the node's latest full command ran on the right machine; the install output showed accepted; the service is active; logs have no persistent 401/403/TLS/DNS errors. Old nodes must be reinstalled with the full command, not just restarted.

Browser CORS errors on the public API

curl works but the browser fails: the origin is not in DEVELOPER_API_ORIGINS. Add the full origin (https://status.example.com), no path, no *. Production must be HTTPS; HTTP is for local development only.

Backup and restore

• Restore requires preview and a confirmation word; merge and replace are supported.
• The Worker keeps a pre-restore R2 snapshot; on failure keep the snapshot and check logs instead of clicking repeatedly.
• Agent tokens in sensitive backups are re-wrapped on restore, so nodes keep authenticating after a cross-account move.
• Normal backups contain no tokens; high-frequency history is not in the JSON; reuse the original R2 when migrating.

Disk capacity display

agent_metrics.vps_info.total_disk_gb is the system root filesystem capacity, not a sum of mounts; same-device bind mounts are not double counted.

Themes and Canvas themes

Only theme packages are open in the current build; there is no plugin runtime. Use a CSS theme for colors and spacing only; use a Canvas theme to fully rewrite the public page layout, interaction or charts. Canvas themes run in a sandbox iframe without same-origin access, read public state only through the message protocol, and cannot reach the network or the host page directly.

• Uploads start disabled; an administrator verifies the SHA-256 and enables them manually. Disabling restores the original UI immediately.
• Do not distribute type: "plugin" ZIPs; the plugin upload and plugin message protocol from older tutorials were never open in the current build.
• A separate panel uses the public v1 API, deploys on its own domain, and needs an exact DEVELOPER_API_ORIGINS allowlist.

Free tier

Economic mode defaults to 15-minute healthy-target probes and Agent batches, 10-minute task claiming, daily ordinary update checks, and approximately 2-minute retries for failed targets. This materially reduces request and Unbound pressure for 100 VPS compared with the old 5-minute model; metrics may be up to 15 minutes old while recovery checks remain short. Keep Dashboard alerts for Workers, Durable Objects, D1 rows, and R2 operations, verify that old Agent versions are gone, and move to Workers Paid if the account still approaches 80%.

Current state (1.1.93): agent telemetry buffers and probe history now live in shared Durable Objects, and D1 writes only fall back when the buffer fails. At the deployed 5-minute reporting cadence, Workers, Durable Objects, D1 and R2 all stay inside the free tier (D1 rows read is the tightest ledger). Use the usage model together with the target deployment's Cloudflare bill for exact ratios instead of extrapolating the old static 100-node budget.

A node cannot reach Cloudflare / Fastly / Akamai

Some networks cannot reach Cloudflare-fronted CDNs at all, so installs, reporting and auto-updates fail. Run a plain TCP relay on any host that can reach the site (TLS/SNI/Host pass through unchanged — no domain, certificate or CDN needed):

On the relay host (it must be able to run curl -fsS https://sla.niekaixiang.com/api/health):

sudo apt install -y socat
sudo systemd-run --unit=nie-sla-relay socat TCP-LISTEN:443,fork,reuseaddr TCP:sla.niekaixiang.com:443

Restrict port 443 to the relayed node's IP in your firewall and re-create the unit or boot script after a reboot. Then point the two official hostnames at the relay on the restricted node and run the panel-generated install command as usual:

echo "<relay-ip> sla.niekaixiang.com api-sla.niekaixiang.com" | sudo tee -a /etc/hosts
curl -fsS https://sla.niekaixiang.com/api/health

TLS validation, the Host header and the update download base all stay on the official domain, so reporting, tasks, WebSocket and auto-update work through the relay. If only IPv6 or an alternate port is reachable, try curl -6 -fsS https://<domain>/api/health or curl -fsS https://<domain>:8443/api/health first.

Installer no longer accepts --token (1.1.65+)

To keep the token out of ps output and shell history, setup.sh, install-mac.sh and quick-install.sh now reject --token and ask for the environment variable or interactive input instead:

NIE_SLA_AGENT_TOKEN='...' sudo -E bash setup.sh --non-interactive

Panel-generated one-click commands already use environment variables and one-time credentials and are unaffected.

Proxy checks stay offline or time out

Check the version of the proxy target's executing Agent first. Releases up to 1.1.53 lack the 1.1.57 Reality handshake buffer fix, so Reality nodes time out at exactly 5 seconds with stage=connect / timeout while handshake and first-byte timings stay -. Fix it by upgrading the executing node to v1.1.57+ (re-run the panel-generated deploy command) or by switching the target's executing Agent to an upgraded node. If every sample still fails afterwards, re-check the share link and parameters (Reality public key and short ID are required).

The panel shows a new version but nothing ever updates

Online updates for one-click deployments are executed by the NIE-SLA Online Update workflow in your deployment repository on GitHub Actions, which checks the official stable release every six hours. It does not run inside the Worker, so the Worker cannot upgrade itself; the panel's update card only reports the current and latest versions.

If the Actions tab shows "Get started with GitHub Actions" (no workflows at all), the one-click deploy did not copy the workflow into the repository. Install it once from the browser (the update logic always lives in the official repository, so this is a one-time step):

1. Open the deployment repository's Actions tab → click set up a workflow yourself;
2. Paste the snippet below and press Commit changes;
3. Then pick NIE-SLA Online Update in the sidebar → Run workflow.

name: NIE-SLA Online Update
on:
  workflow_dispatch:
  schedule:
    - cron: "17 */6 * * *"
permissions:
  contents: write
jobs:
  update:
    uses: 3257085208/NIE-SLA/.github/workflows/nie-sla-update.yml@main

When a deployment stays on an old version, check in order:

1. Are Actions enabled? Repository → Settings → Actions → General, allow workflows to run (fresh or forked repositories may have Actions disabled).
2. Are there any runs? The repository's Actions tab should list scheduled "NIE-SLA Online Update" runs. No runs at all: use the install snippet above; once installed, click Run workflow to trigger one immediately.
3. Read the failing log: open the failing run's last step:
   • no online-update baseline: the repository content does not match the official baseline for its version; synchronize manually once;
   • Deployment files differ from the official … baselines: the repository contains changes beyond the official release (only wrangler.jsonc may differ);
   • dependency or build errors: re-trigger once from the latest branch.
4. Wait for the Cloudflare build: after the workflow pushes, Cloudflare Workers Builds still needs about 1–3 minutes to build. Hard-refresh the panel and press "Check for updates".

Without GitHub Actions you can update manually: synchronize the repository to the latest official version and run npm run deploy, or simply redeploy from the latest one-click template (which also brings the newest Durable Object bindings and internal secret provisioning).

Nodes follow the official channel when the instance lags (v1.1.93+)

The workflow above updates the instance (Worker and static assets). Agents have their own channel: since v1.1.93, when the instance publishes a version older than the official latest, nodes follow the official release channel directly (update-manifest.json and bin/SHA256SUMS served from https://sla.niekaixiang.com), verify it and update themselves instead of staying pinned to the instance. Rules:

• The fallback only runs while the instance has automatic updates enabled (auto_update); an instance that explicitly disables them keeps its nodes untouched.
• Whenever the instance publishes something newer than the node, the instance still wins (self-hosted distribution first).
• Environment overrides: NIE_SLA_OFFICIAL_UPDATE=0 disables the fallback; NIE_SLA_OFFICIAL_UPDATE_BASE=https://… points it at your own mirror.
• Check cadence: every hour by default when the instance does not configure one (AGENT_UPDATE_CHECK_SEC, 900–86400 seconds); an interval from the instance policy wins.

So even if an instance's deployment pipeline stalls, nodes keep receiving official fixes; the instance itself still needs the workflow above (or a manual deploy).