Sensor troubleshooting

It stays pending

pending means the sensor registered but no report has arrived. Registration and reporting use different ports, so the usual cause is a firewall that allows 9090 but not 9092.

1. Check the sensor’s own logs - run with --log-format text --log-level debug.
2. Confirm outbound TCP to the ingest endpoint on 9092.
3. Confirm the local health endpoint responds: curl 127.0.0.1:18080/healthz.

See network requirements.

Bootstrap fails

Symptom	Cause
Token rejected	Already redeemed - tokens are single-use - or expired
Machine ID mismatch	The token was pinned to a different machine ID
Connection refused on 9090	Egress blocked, or wrong region endpoint

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:

The port is not in the list. Only --ports are tried. A service on 8443 is invisible unless you say so - and 8443, 9443 and 10443 are extremely common internally.

The target was not in scope. CIDR expansion covers IPv4 only. IPv6 discovery is not implemented yet, so v6-only hosts are missed.

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.