The sensor will not enrol

You have run the installer on a machine and the machine has not appeared under Endpoints in the console. This article lists every reason the platform refuses an enrolment, gives the exact wording of each refusal so you can search for the one you saw, and then covers the case where enrolment succeeded and the endpoint still shows nothing.

First, one distinction that causes more confusion than anything else here. There are two secrets and they are not interchangeable. An enrolment token starts with zqe_, is minted by you in the console, is short-lived, and its only power is to create one endpoint record. A sensor token is issued by the platform as the result of a successful enrolment, belongs to one machine, and is what that machine uses from then on. Revoking an enrolment token does not disable the machines that already used it — they hold their own credential.

Start with the installer exit code

The zentryq-sensor enroll command is deliberately specific about how it failed, because the remedies are completely different and the packaging scripts branch on the code. On Linux and macOS the maintainer script always exits 0 itself, so a failed enrolment never leaves the package manager half-configured — which means the exit code you want is the one from the enrol step, in the installer output or the service log, not the one from apt or Installer.app.

The six ways a token is refused

All six come back as HTTP 401 with a JSON body of the form {"error": "..."}. The installer prints the server's reason verbatim, so the string below is what you will read on the machine.

Four of them are wrapped with the decisive detail when the platform knows it, and the wrapped form is what you should search for because it tells you the answer outright:

enrolment token has been revoked (revoked 2026-09-01T10:22:14Z)
enrolment token has expired (expired 2026-08-25T09:00:00Z)
enrolment token has reached its maximum number of uses (3 of 3 used)
enrolment token was not issued for this product: token was issued for pam-agent,
  this is the sensor enrolment endpoint
enrolment token was not issued for this platform: token is for windows,
  this host is linux

There is a seventh, benign one. enrolment token not recognised: token state changed during enrolment, please retry means two machines redeemed the same token in the same instant and this one lost the race on the use counter. A retry succeeds. You will only ever see it when a fleet boots from one golden image.

When the request was wrong, not the token

These come back as 400, and they mean the installer sent something the enrolment endpoint could not use. In normal use you will only meet the first one.

no enrolment token supplied — pass one with SENSOR_ENROLL_TOKEN (Windows) or
  ZQ_ENROLL_TOKEN (Linux/macOS)
could not read enrolment request: <detail>
enrollment_fingerprint is required
fingerprint is required
organization_id is required

no enrolment token supplied means the token never reached the agent, and that is more common than a bad token. Environment variables are unreliable on two of the three platforms, which is why a file-based route exists: apt and dnf do not reliably forward the invoking environment to maintainer scripts, and a macOS package opened from Finder runs its scripts with no useful environment at all. Write the token to /etc/zentryq/enrollment-token before installing, and the API base URL to /etc/zentryq/api-url if it is not the default. Both are whitespace-stripped, so a file pushed by an MDM with Windows line endings is handled.

If you are minting a token rather than redeeming one, four validations refuse rather than silently correcting you: product must be one of: sensor, pam-agent, platform must be one of: any, windows, linux, darwin, max_uses must be greater than zero when set, and ttl_seconds may not exceed 7776000 (90 days) — enrolment tokens are short-lived by design. The last is a refusal and not a clamp on purpose: an operator who asked for a year has made an assumption about how this works, and quietly issuing a 90-day token leaves them to discover the difference when their fleet stops enrolling.

Two errors that do not exist

This section exists so that you do not spend an afternoon looking for a message we never wrote. Both of these are things administrators reasonably expect to see, and in this product neither produces its own error.

There is no clock-skew error

A machine whose clock is wrong does not get told so. The wrong time makes TLS certificate validation fail inside the HTTP client, and that surfaces through the ordinary transient path: enroll: could not reach <api> right now (<TLS error>), exit 4, and a service that retries forever. So the symptom of a badly skewed clock is an endpoint that never appears and a log full of connection failures mentioning certificates. If the network is otherwise fine, check the clock before the firewall. There is a clock-skew allowance elsewhere in the product, on threat-hunting queries, and it is unrelated.

There is no duplicate-host error

Enrolling the same machine twice is not an error and is not refused. The host fingerprint is the conflict key, so a second enrolment updates the existing endpoint record rather than creating a new one, and the installer prints enroll: re-enrolled (this host was already known) as sensor <id>. This is deliberate: a repair install, a rename or a re-image must not litter your endpoint list with ghosts. It also means you cannot create a duplicate by accident, and that a machine which came back is the same row, with hostname, platform, architecture and public key refreshed and any earlier revocation cleared.

Nor is there an endpoint-specific message for insufficient privilege. If your console user cannot mint or revoke a token, the shared middleware answers {"error":"insufficient permissions"} with 403 — a permissions question, not an enrolment one. See Roles and permissions.

Enrolled, but nothing appears

A record proving a token was spent is not evidence that an agent is alive, so the console counts those states separately. Open the enrolment token and read its progress view: it counts awaiting first event apart from reporting. A machine in the first bucket enrolled successfully and has never sent telemetry. An unknown token id there is a 404 rather than an empty list, so a typo cannot render a permanently cheerful waiting…

Three log lines from the service explain most of what lands in that bucket:

sensor: no credential configured — this endpoint will not report. Re-run the
  installer with an enrolment token from Settings -> Endpoints -> Enrolment tokens.
sensor: enrolment token rejected — <reason>. A new token must be issued in the
  console; this endpoint will not report until it is.
sensor: enrolled, but could not persist the credential to <path>: <err>

The third is the nastiest. Enrolment succeeded, the machine holds a working credential in memory, and could not write it to disk. It works until the service restarts, then has to redeem the enrolment token again — which fails outright if the token was single-use. Fix the permissions on the configuration path and re-run enrolment with a fresh token.

The order to work in

1. 1

   Read the exact refusal, not a summary of it

   The six token messages have six different remedies and only one is mint a new token. not recognised usually means a copy-paste fault, and re-minting a token you then paste wrongly again wastes another twenty minutes.

2. 2

   Confirm the token reached the machine at all

   If the message is no enrolment token supplied, nothing was wrong with your token. Put it in /etc/zentryq/enrollment-token and re-run, rather than relying on an exported variable — especially on macOS.

3. 3

   Check the service is running

   sc query ZentryQSensor on Windows; sudo systemctl status zentryq-sensor and sudo journalctl -u zentryq-sensor -n 50 on Linux; sudo launchctl print system/eu.zentryq.sensor | head -20 on macOS. A stopped service cannot retry a deferred enrolment.

4. 4

   Re-enrol by hand once you have a good token

   sudo zentryq-sensor enroll --token <TOKEN> --api <URL> --config /etc/zentryq/zentryq-sensor.yaml && sudo systemctl restart zentryq-sensor. Drop the systemctl half on Windows and macOS and restart the service the platform's own way.

5. 5

   Judge success from the console

   The authoritative check is the endpoint appearing under Endpoints with a recent check-in. A machine can hold a valid credential and still fail to deliver telemetry — see An endpoint stopped reporting.

One platform step that is easy to miss: on macOS 11 and later the sensor needs Full Disk Access granted manually under System Settings, Privacy & Security, adding /usr/local/bin/zentryq-sensor. Enrolment works without it; the file and process channels report far less than they should. For minting, capping and revoking tokens across a fleet, read Enrolment tokens.