NetClamp docs

Troubleshooting

If you’re here because something’s broken, work through the diagnostics top-to-bottom. The first matching pattern is usually the right one.

SPA shows "Disconnected"

Check the NetClamp service is running:

sc query NetClamp

If STATE shows STOPPED, start it:

gsudo --direct cmd /c "sc start NetClamp"

If start fails, the next stop tells you why:

Get-Content C:\ProgramData\NetClamp\logs\service.log -Tail 50

Common log lines:

Failed to bind REST API port 9845

Another process is on 9845. Either kill it (netstat -ano | findstr 9845) or change the bind in config.toml.

Invalid bind config

Typo in config.toml. Fix and restart.

WFP session open failed: ERROR_…

BFE is down. Start it: gsudo --direct cmd /c "sc start bfe".

"Pair browser" loop

You paste a token, click Pair, and bounce back to /setup.

  1. Verify the token is the current one:

    Get-Content C:\ProgramData\NetClamp\auth.token

  2. If you rotated the token recently, every paired browser must use the new value. Old tokens are invalid immediately.

  3. If localStorage is disabled (private/incognito), the SPA can’t persist the token — switch to a regular window.

A rule won’t sync (stuck on pending_* or broken)

Each rule has a sync column in the Rules table:

  • synced — rule is live, nothing to do.

  • pending_create / pending_update / pending_delete — the service is mid-sync. Should clear within a couple of seconds.

  • broken — the firewall layer refused the rule. Click Retry on the row; if it still fails, Delete + recreate. If the rule keeps failing, restart the NetClamp service (the most common cause is stale state from a previous version).

The driver won’t load

/api/v1/status shows "kdrv_active": false.

  1. Confirm test-signing mode is on:

    bcdedit | findstr testsigning

    Expect testsigning Yes. If No, enable + reboot:

    gsudo --direct cmd /c "bcdedit /set testsigning on"
# … reboot …

  2. Check the driver service exists:

    sc query NetClampKdrv

    If "service does not exist", the installer skipped it (driver file was missing at install time). Re-run the installer with the .sys present.

  3. Try starting it:

    gsudo --direct cmd /c "sc start NetClampKdrv"

    Exit code 577 = ERROR_DRIVER_BLOCKED — driver was rejected by Windows signature check. Verify test-signing is on AND the machine was rebooted after enabling it.

Bandwidth chart shows a flat line

The throughput sampler stopped. Causes:

  • WFP session torn down by BFE bounce — should auto-recover. Check bfe_restarts in /api/v1/status. If it’s incrementing every minute, something is forcibly bouncing BFE; check Defender update schedule.

  • Sampler thread panicked — extremely rare. Restart the service.

Rate-limit isn’t actually limiting

  1. Confirm the rule’s sync column shows synced.

  2. Confirm kdrv_active: true if you need precision better than ±15%. Without the driver, the userspace fallback uses on/off cycling — fine in aggregate, jittery instantaneously.

  3. Run the e2e shaper diagnostic:

    gsudo pwsh -File scripts\e2e-shaper-test.ps1 -CapKBps 200 -PayloadMB 5

    Exit 0 means the shaper is working end-to-end. Non-zero dumps WFP
    driver counters for the support ticket.

"Operation cancelled by user" during install

You hit No on the UAC prompt. The installer needs Administrator — re-run and accept.

Service is running but /api/v1/status returns 401

Bearer token wrong. The SPA’s localStorage and auth.token on disk are out of sync.

Recovery: clear browser storage (Settings → Security → Forget this browser), then re-paste the current token from C:\ProgramData\NetClamp\auth.token.

Credit activation returns "hwid_mismatch"

The activation token is bound to a different machine’s HWID. Either:

  • You tried to activate a credit on a machine other than the one it was purchased for, OR

  • You reinstalled Windows on physically-different hardware (board swap, etc.) and the HWID hash drifted.

Use the Transfer flow from the source machine (or, if that machine is gone, contact support — we can issue a rebind manually with proof of purchase).

Log locations

C:\ProgramData\NetClamp\logs\service.log.*

Service. Rotated; check the most recent.

target\service-stdout.log

Dev console-mode service stdout.

target\tray-stdout.log

Dev console-mode tray stdout.

C:\work\NetClamp\target\install-*.log

Inno Setup install log (one per install).

Windows Event Viewer → Application + System

SCM start/stop events for NetClamp + NetClampKdrv.

How to reach support

  • Reproducible bug or feature gap — email [email protected] with the service log, /api/v1/status JSON, and reproduction steps. Run netclamp diag dump and attach the output — it packages all of the above in one redacted bundle, safe to share.

  • Activation or billing problem — email [email protected] with your order number from the Lemon Squeezy receipt.