Sensor troubleshooting

It stays pending

pending means the sensor registered but no report has arrived yet. Registration and reporting both go out over HTTPS on 443 - reporting simply adds the sensor’s client certificate, which the edge verifies before forwarding (see network requirements). A firewall that lets registration through lets reporting through too, so pending is usually one of: outbound 443 to api.nextpki.com blocked after registration, the sensor process not actually running its scan loop, or the sensor paused from its configuration.

1. Check the sensor’s own logs - run with --log-format text --log-level debug.
2. Confirm outbound HTTPS (443) to api.nextpki.com.
3. Confirm the local health endpoint responds: curl 127.0.0.1:18080/healthz.

Bootstrap fails

The installer and the sensor print the reason in plain words - the table maps them to a cause.

Message	Cause
token_already_used	Already redeemed. Tokens are single-use
token_expired	The token’s TTL passed before it was redeemed
token_unknown	Typo or a truncated copy/paste; the server has no such token
machine_id does not match bootstrap hint	The token was pinned to a different machine ID
A signature or checksum error from install.sh	Stop. The download did not come cleanly out of the release process; report it to security@nextpki.com

A consumed token cannot be reused. Create a new one; this is by design, since a reusable registration token would be a durable credential sitting in your configuration management.

It reports fewer certificates than expected

In rough order of likelihood:

A network is waiting for confirmation. A sensor that has moved reports the network it now sits in and does not scan it until somebody confirms it. The sensor’s detail page shows the network waiting for a decision, and the log says left alone until somebody confirms them. This is the most likely reason a sensor that was reporting yesterday suddenly finds nothing today, and it is the intended behaviour, not a fault - see automatic discovery.

The port is not in the list. Only configured ports are tried: the target’s own ports if it has any, --ports otherwise. A service on 8443 is invisible unless you say so - and 8443, 9443 and 10443 are extremely common internally.

The protocol was guessed from the port. A mail service on a non-standard port is probed as HTTPS and reports nothing. Give that target an explicit protocol.

A target was skipped. A name that does not resolve, a bad port expression or a range past the address limit takes that target out of the cycle, and only that one. The log says scan target skipped with the reason.

The target was not in scope. A CIDR is expanded as written, v4 or v6. There is still no v6 sweep, and there will not be one - a /64 is too large to walk. What exists instead is IPv6 discovery: the sensor probes the neighbours the kernel already knows, on Linux, if you turn it on. It starts near empty and fills as the host talks to its segment, so a v6-only host you need in the inventory today belongs in the target list.

An exclude is broader than you think. Excludes win over includes. Check for a CIDR that swallowed the range.

The handshake did not complete. A host requiring a client certificate, or one that fails on an unexpected SNI, yields no certificate. This is a genuine gap, not a silent drop - raise the log level and you will see the failures.

A middlebox interfered. TLS-inspecting proxies present their certificate. If everything internal suddenly appears to be issued by your own firewall vendor, that is what happened, and the finding is real: that is what clients see too.

Duplicate-looking entries

If two entries look like the same certificate, compare fingerprints. Identical fingerprint means one certificate with multiple observations - that is correct behaviour, not duplication. Different fingerprints mean genuinely different certificates, common on load-balanced hosts mid-rollout.

Reports arrive but the sensor shows stale

stale means it was reporting and stopped. Check whether the process is running, whether the interval is longer than you remember, and whether the mTLS client certificate is still valid - it has its own expiry, visible in the Console under Sensors.

Getting useful logs

nextpki-sensor run --log-format text --log-level debug \
  --targets 10.0.0.0/28 --scan-profile conservative

Test with a small CIDR first. A /28 is sixteen addresses and finishes fast, which makes it a much better debugging target than the /16 you actually want to scan.