Troubleshooting

Common fixes for offline agents, empty maps, TLS/MITM failures, SSO loops, and permission issues.

Offline agent

Symptoms: machine missing or not Online under Installed agents.

Check:

1. Windows: NP4th service Running (scheduled probes while the PC is on); tray NP4th.exe for the signed-in user (UI / dashboard run-now).
2. macOS: launchd label com.didurlabs.np4th loaded; agent binary /Applications/NP4th.app/Contents/MacOS/NP4th --agent.
3. Agent key still enabled under Settings → Agent keys.
4. Outbound HTTPS to https://app.np4th.com (proxy/firewall allowlist).
5. client-config.json has the correct tenantSlug, clientKey, and apiBaseUrl.

Online requires a heartbeat or run upload within about 15 minutes.

Agent never updates (Windows)

Silent updates use the LocalSystem service (no UAC). The tray only signals ProgramData\NP4th\updates\check-now.flag.

1. services.msc → NP4th is Running (reinstall NP4thSetup.exe if missing). The service also relaunches a missing tray after updates.
2. Confirm tray Automatic updates is checked (default on). Manual Check for updates still works when it is unchecked.
3. From the dashboard Installed agents page, use Force update on online Windows agents, or tray Check for updates, or sign out/in so the tray requests a check at login (when automatic updates are on). Stable checks about every 6 hours; nightly hourly.
4. Server has published NP4thSetup.exe + version.txt newer than the installed agent.
5. Status file (optional): %ProgramData%\NP4th\updates\update-status.txt.
6. Tray tooltip / About shows vX.Y.Z. After a silent update you should see an NP4th updated balloon.

Tray icon missing (Windows)

1. Confirm NP4th.exe is running (Task Manager). If not, start NP4th from the Start menu once — Startup / HKCU Run should keep it after reboot.
2. If a silent update just ran, wait up to a couple of minutes for the update service / NP4thWatchdog scheduled task to relaunch the tray, or sign out/in.
3. Check the notification overflow (^) — Windows may hide new icons.
4. Avoid launching multiple copies; a second start focuses the existing tray window.

Installs register a SYSTEM task NP4thWatchdog (every 3 minutes) that restarts the update service if a silent Setup left it stopped, and requests a tray relaunch when NP4th.exe is missing.

Empty map / no hops

Symptoms: Runs show latency but the Path map is empty.

• Expand a computer under Test runs, then click a target to plot paths.
• Private/reserved hops are skipped for geo—you may see fewer plotted points than traceroute hops.
• Ensure the target has Trace enabled in Config → Targets, and that agents synced after you saved.
• Use Clear map then re-select targets if the layer looks stale.

TLS / MITM failures

Symptoms: TCP succeeds but TLS fails, or certificate validation errors appear.

• TLS performs handshake and certificate validation to catch MITM.
• Corporate SSL inspection can fail TLS unless the inspecting CA is trusted on the endpoint.
• Confirm the Port column matches the HTTPS/TLS port for that destination.
• Compare with Internet check (cloud) to see whether the failure is path-specific.

SSO loops or lockouts

Symptoms: redirect loop, unexpected role, or inability to sign in after Enforce SSO.

1. Confirm Entity ID and ACS URLs use your exact tenant slug.
2. Re-test with Test SSO claims before enforce.
3. Verify Email domains and group object IDs/names.
4. Owner break-glass: /dashboard/local.html or ?local=1 / ?nosso=1.
5. Temporarily disable enforce, fix mapping, then re-test.

See SSO / SAML.

Permissions matrix

Still stuck?

Contact support from the marketing site contact form, and include tenant slug, approximate time of the issue, agent device name, and whether the failure is endpoint-only or also visible in Internet check (cloud).