Troubleshooting¶

Feature-specific guidance also appears under certificate workflows, Delegated DNS-01 and Entra ID. This page covers issues that cut across features.

The agent says setup is required or cannot authenticate¶

Open Settings, supply either an install token or an existing agent API key, then select Test connection. A saved local credential is not proof that the platform accepted it:

428 Precondition Required means an administrator must approve the newly enrolled device on the platform's Agents page.
401 Unauthorized means the key is wrong, expired or revoked.
A network or TLS error means the configured API/server URL cannot be reached or trusted from the service host.

Use Activity for the readable error. Routine activity stays in the agent; only errors are written to the Windows Application event log. Enable debug logging temporarily from Settings → Log retention when normal activity does not contain enough detail.

A workflow cannot change its CA, account or certificate names¶

This is intentional. The domain set, ACME account, directory/profile, key type and renewal identity are part of persisted order and replacement policy. Changing them underneath an existing workflow can produce errors such as certificate policy changed; use a new certificate ID or explicit migration.

Create a new workflow for a different issuance identity. Existing workflows can still change their display name, automatic-renewal preference, DNS credential, output password, and storage/installation plans.

Choosing the correct workflow action¶

Action	Use it when
Issue / replace	The workflow has never issued, or its previous certificate was revoked and a replacement is intended.
Renew now	A currently issued certificate needs a new ACME order before its scheduled renewal time.
Retry installation	Issuance already succeeded but saving, importing, binding, reloading or restarting failed. It reuses the issued certificate.
Auto-renew	The service should act automatically when the persisted renewal schedule says the certificate is due.

Manual actions and first issuance run immediately. Weekly renewal windows constrain only unattended renewal and automatic installation retries.

JKS issuance or installation fails¶

Confirm that the workflow points to the exact absolute .jks file, the Java runtime's real keytool.exe, the intended alias, and the existing keystore/key password. The containing application directory must already exist. A JKS password must be supplied because Java must be able to open the keystore after the agent writes it.

If keytool reports an invalid CSR, inspect Activity for the command phase and verify that the selected executable is Java keytool, not another file with the same name. If certificate import completed but the selected Tomcat/Windows service did not restart, use Retry installation. The agent recognizes an already imported reply and continues with the exact configured service restart instead of trying to create another certificate order.

An automatic update is offered but will not install¶

The updater accepts a release only when its two metadata sources agree. It also verifies the MSI SHA-256 digest, Authenticode signer and MSI product identity before starting Windows Installer. Check Activity for a source-disagreement, signature, hash or installer error. A transient disagreement can mean one release endpoint has not finished publishing; retry after both endpoints contain the same release.

"401 Unauthorized" with no other detail¶

CertIntel deliberately gives the same generic 401 for a wrong secret, a revoked key, and an expired key - there's no way to distinguish them from the response, so a leaked key prefix can't be used to probe a key's state. Check, in order:

Is the key/prefix actually the one you think it is? Compare against the API Keys or Agents page.
Has it expired or been revoked? Both show clearly in the dashboard even though the API response doesn't distinguish them.
For an agent key specifically: is it still pending approval? See Install tokens & enrollment - a pending key returns a distinguishable 428, not a 401, so if you're seeing a plain 401 the key isn't the pending-approval case.

"404 Not Found" for something you're sure exists¶

CertIntel answers a cross-tenant or cross-organization id with 404, never 403 - this is deliberate, so a permission boundary never reveals whether something exists on the other side of it, only that you can't see it. If you're confident the resource exists, check that you (or the API key) are scoped to the right organization, and that a tenant-wide/organization-switcher filter isn't hiding it.

A write-scoped key can't do something it should be able to¶

A write key holds only ingest permissions - it cannot read data back, manage targets, or do anything outside submitting reports. If it also looks like it can't submit a specific kind of report, check whether it was narrowed to a subset of renewals / checkins / internal_certs at creation - see API keys & authentication.

An organization administrator can't see something a tenant administrator can¶

This is usually correct behavior, not a bug: most resources are scoped to one child organization, and an organization-level role only ever sees its own organization's data - even tenant-wide (organization-less) resources are invisible to it. Tenant-wide visibility requires tenant administrator authority.

DNS-01 challenge never resolves¶

Almost always one of:

The CNAME target was copied with a stray trailing character, or without the trailing dot some DNS providers require - use the copy button on the delegation record rather than retyping it.
Cloudflare: the record is proxied (orange cloud) instead of DNS only (grey cloud) - see Delegated DNS-01 (dashboard).
The CNAME hasn't propagated yet - DNS propagation delay, not a CertIntel issue; wait out your provider's TTL.

Role mapping is default-deny - see OIDC / SSO overview. Check that the claim value your identity provider actually sends matches a configured mapping (or a CertIntel.* convention value) exactly, byte for byte.