Structured per-target error codes emitted by every distribution module, the error class each code maps to, and which classes the fan-out per-target retry re-attempts. Codes appear in the error_code field of the per-target results (last_target_results) on the distribution and in job logs.
Retry policy is based on a normalized error class, not on raw error strings. Each code maps to one of five classes; only the first two are re-attempted by fan-out per-target retry.
Class
Meaning
Retried by fan-out?
network
Timeout, connect failure, DNS resolution failure.
Yes
io_transient
Broken pipe, connection reset, transient SFTP/API failure — likely to succeed on retry.
Yes
io_permanent
Remote permission denied, no space left, quota/ownership conflicts — operator action needed.
The module credential referenced by the target could not be resolved.
No code for external secret stores
A credential read from an external secret store is resolved before any target is attempted, so a store failure has no target to attach a code to. It is reported at the job level instead — the job status and last error name the credential, the store and the underlying failure. There is deliberately no SECRETSTORE_* code, because no target result could ever carry one.
SFTP session could not be opened or an SFTP operation failed.
FILE_UPLOAD
io_transient
Writing a PathSet file on the target failed.
SCRIPT_EXIT_NONZERO
io_transient
The ActionSet script ran but exited with a non-zero status.
SCRIPT_FAILED
io_transient
The ActionSet script could not be executed.
SSH_VALIDATION
validation
Pre-flight validation of the SSH deployment inputs failed.
SSH_HOST_KEY_ALGO
validation
Host-key negotiation failed before any key was presented: the server offers only key types CertAutoPilot does not advertise once verification is enabled — in practice a DSA-only server. Not retried, and there is nothing to approve. Add a modern host key to the server, or turn verification off for that target. A server that merely dropped the pinned key type does not land here: the other types stay on offer, so it is reported as SSH_HOST_KEY_CHANGED and can be reviewed.
SSH_HOST_KEY_CHANGED
validation
The server presented a host key that does not match the one pinned for this target. Nothing was deployed, and the run is not retried — review and approve the new key on the target. Only raised when host-key verification is enabled on that target.
NTLM / Basic / Kerberos authentication rejected. For Kerberos, check the realm, that the target is addressed by AD FQDN, and that this host's DNS resolves AD records (or set the KDC Address field).
WinRM connection or in-flight transport to the Windows host failed.
IIS_AUTH
auth / validation
NTLM / Basic / Kerberos authentication rejected, the account lacks store/binding permissions, or a permanent Kerberos configuration error (qualified username, IP-addressed target, missing realm).
IIS_PFX_FAILED
validation / io_transient
Building the PKCS#12 bundle locally failed (validation — cert/key problem), or uploading it over WinRM failed (io_transient — retried).
IIS_IMPORT_FAILED
io_permanent
Importing the PFX into the Windows certificate store failed, or the script result could not be parsed.
IIS_BINDING_NOT_FOUND
validation
No HTTPS binding matched the configured filter (or, in all_sites, no binding on any non-excluded site).
IIS_BINDING_AMBIGUOUS
validation
More than one binding matched in single mode — refusing to guess.
IIS_BINDING_FAILED
io_permanent
No bindings could be updated (including the all-matched-bindings-are-CCS case).
IIS_APPPOOL_DETECT_FAILED
validation
Detecting the application pools to recycle failed.
IIS_APPPOOL_RECYCLE_FAILED
io_permanent
Recycling one or more application pools failed (run is partial).
IIS_VALIDATE_STORE
validation
Post-deploy check of the certificate store failed.
IIS_VALIDATE_BINDING
validation / io_transient
Post-deploy binding check found a mismatch (validation), or the check itself failed at the transport level (io_transient — retried; the bind already succeeded).
IIS_MODULE_MISSING
validation
A required server-side component (e.g. the WebAdministration PowerShell module) is missing.
IIS_SITE_NOT_FOUND
validation
The configured IIS site does not exist — or the resolved placement names no site at all (a site-less per-certificate override inherited onto an all_sites target; reported by Execute and Dry Run).
Dual-class rows: the same code covers two failure natures; the module sets the
class explicitly at the failure site, so fan-out retries only the transient one.
The certificate is uploaded to a Cloudflare zone as a Custom Certificate (Business/Enterprise plan) over the Cloudflare API; renewals update it in place.
Code
Class
Meaning
CLOUDFLARE_CONNECT
network
Cloudflare API (api.cloudflare.com:443) unreachable — check egress/DNS and retry.
CLOUDFLARE_AUTH
auth
API token rejected — verify the token is active and carries Zone → SSL and Certificates → Edit on the target zone.
CLOUDFLARE_PLAN
validation
The zone's plan does not permit Custom Certificates — upgrade the zone to Business or Enterprise.
CLOUDFLARE_NOT_FOUND
validation
The referenced zone or custom certificate does not exist — check the zone ID / certificate ID.
CLOUDFLARE_CONFLICT
validation
More than one custom certificate covers the hostname — pin an explicit certificate_id to disambiguate.
CLOUDFLARE_VALIDATION
validation
The request itself is invalid — bad bundle_method/type/geo_restrictions, or a cert/key the API rejected.
CLOUDFLARE_QUOTA
io_transient
API rate limit or custom-certificate quota hit — retried; if persistent, free a custom-cert slot or slow the cadence.
The certificate is imported into an Azure Key Vault as a new version of a KV certificate (AES-256-encrypted PKCS#12 under a random per-import password) over the Key Vault REST API, authenticated via an AAD service principal.
Code
Class
Meaning
AZUREKV_CONNECT
network
Vault or AAD endpoint unreachable (also raised on an unexpected redirect) — check egress and the vault_url.
AZUREKV_AUTH
auth
Token rejected or missing permission — fix tenant/client/secret, grant Key Vault Certificates Officer (or access-policy Get+Import+List), or allowlist CertAutoPilot's egress IP in the Key Vault firewall.
AZUREKV_NOT_FOUND
validation
Vault or certificate not found — verify the vault URL and certificate name.
AZUREKV_CONFLICT
validation
A soft-deleted certificate holds the name (az keyvault certificate recover, or purge — blocked by purge protection — or pick a different cert_name); also covers a pending certificate operation.
AZUREKV_VALIDATION
validation
Bad vault_url/cert_name, or Azure rejected the PFX.
AZUREKV_QUOTA
io_transient
Key Vault throttling (429) — retried automatically with backoff.
Certificates on MerlinCDN are immutable — each deploy uploads a new cert, then binds it by re-pointing the distribution's canonical name. The codes below distinguish an upload failure (nothing bound yet) from a bind failure (a new cert was uploaded; the module best-effort deletes that orphan).
Code
Class
Meaning
MERLINCDN_CONNECT
network
MerlinCDN API unreachable.
MERLINCDN_AUTH
auth
Personal access token or org/workspace headers rejected.
MERLINCDN_NOT_FOUND
validation
The referenced distribution or canonical name does not exist.
MERLINCDN_CONFLICT
io_permanent
Name/state conflict on the CDN.
MERLINCDN_QUOTA
io_transient
API quota / rate limit hit.
MERLINCDN_UPLOAD
io_permanent
Uploading the new certificate failed (nothing was bound).
MERLINCDN_BIND
io_permanent
Re-binding the canonical name to the new certificate failed; the just-uploaded cert is best-effort removed.
On-premises Microsoft Exchange, deployed over WinRM + the Exchange Management Shell. Every renewal imports a new thumbprint (import → enable → optional remove-old).
Code
Class
Meaning
EXCHANGE_CONNECT
network
WinRM unreachable — host/port/network.
EXCHANGE_AUTH
auth
WinRM authentication rejected, or a TLS-verify / Kerberos misconfiguration (terminal).
EXCHANGE_EMS_UNAVAILABLE
validation
The Exchange /PowerShell RBAC session did not open or its cmdlets did not import — not a real Exchange server, remote PowerShell disabled for the account, or the account lacks an Exchange RBAC role for the certificate cmdlets.
EXCHANGE_CREDENTIAL_MISSING
validation
No or malformed exchange_winrm credential (missing username/password).
EXCHANGE_IMPORT
io_permanent
Import-ExchangeCertificate failed.
EXCHANGE_ENABLE
io_permanent
Enable-ExchangeCertificate failed.
EXCHANGE_REMOVE
io_permanent
Removing the previous certificate failed (it may still be in use).
EXCHANGE_NOT_FOUND
validation
A referenced Exchange server or certificate was not found.
The certificate, key and chain are imported into the firewall as one named certificate object over the PAN-OS XML API, followed by a partial commit scoped to the API user.
Code
Class
Meaning
PANOS_CONNECT
network
TCP/TLS connection to the firewall management interface failed. Retried.
PANOS_AUTH
auth
Authentication rejected (bad username/password or api_key, or an expired session key). Not retried. Note: username is required even with api_key.
PANOS_IMPORT
io_transient
The certificate import was rejected or failed on the device. Retried — a same-name re-import is idempotent. Note: PAN-OS refuses a self-signed non-CA certificate, and the PKCS#12 passphrase is device-limited to 31 characters (the module already complies).
PANOS_COMMIT
io_transient
The partial commit failed or its job timed out. Retried; a timed-out commit may still complete in the background, and the next run finishes with a commit-only pass instead of re-importing.
PANOS_NOT_FOUND
validation
A referenced object does not exist on the firewall. Not retried.
PANOS_VALIDATION
validation
The device rejected the request as invalid (bad name, vsys set while multi-vsys is off, malformed input). Not retried.