Skip to main content

Distribution error codes

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.

Error classes

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.

ClassMeaningRetried by fan-out?
networkTimeout, connect failure, DNS resolution failure.Yes
io_transientBroken pipe, connection reset, transient SFTP/API failure — likely to succeed on retry.Yes
io_permanentRemote permission denied, no space left, quota/ownership conflicts — operator action needed.No
authSSH/API authentication failure, credential rejected.No
validationCert/key mismatch, invalid path, missing target — the request itself is wrong.No
note

A code that is not mapped to any class (and where the module did not set a class itself) is treated as not retryable.

Cross-module codes

CodeClassMeaning
CREDENTIAL_MISSINGauthThe 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.

SSH

CodeClassMeaning
SSH_CONNECTnetworkTCP/SSH connection to the target failed.
SSH_AUTHauthSSH authentication rejected (key or password).
SFTP_FAILEDio_transientSFTP session could not be opened or an SFTP operation failed.
FILE_UPLOADio_transientWriting a PathSet file on the target failed.
SCRIPT_EXIT_NONZEROio_transientThe ActionSet script ran but exited with a non-zero status.
SCRIPT_FAILEDio_transientThe ActionSet script could not be executed.
SSH_VALIDATIONvalidationPre-flight validation of the SSH deployment inputs failed.
SSH_HOST_KEY_ALGOvalidationHost-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_CHANGEDvalidationThe 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.

Webhook

CodeClassMeaning
WEBHOOK_CONNECTnetworkThe webhook endpoint could not be reached.
WEBHOOK_NON_2XXio_transientThe endpoint answered with a non-2xx HTTP status.

Kubernetes

CodeClassMeaning
K8S_CONNECTnetworkThe API server could not be reached, or a live-picker listing (namespaces / Secrets / workloads) failed for a reason other than RBAC.
K8S_FORBIDDENauthRBAC denied the secret create/update — or, in a live picker, the list verb the listing needs.
K8S_NOT_FOUNDvalidationNamespace or referenced object does not exist.
K8S_APPLY_FAILEDio_transientApplying the Secret failed for another reason.

NetScaler

CodeClassMeaning
NETSCALER_CONNECTnetworkNITRO API unreachable.
NETSCALER_AUTHauthNITRO login rejected.
NETSCALER_UPLOADio_transientUploading the cert/key files failed.
NETSCALER_UPDATEio_transientUpdating the certkey object failed.
NETSCALER_NOT_FOUNDvalidationThe certkey / vserver referenced does not exist.
NETSCALER_LINKio_transientLinking the certificate to the CA chain failed.
NETSCALER_CHAINio_transientInstalling the chain certificate failed.
NETSCALER_OWNERSHIPio_permanentThe object exists but is not managed by CertAutoPilot — refusing to overwrite.

Huawei Cloud

CodeClassMeaning
HUAWEICLOUD_CONNECTnetworkHuawei Cloud API unreachable.
HUAWEICLOUD_AUTHauthAK/SK authentication rejected.
HUAWEICLOUD_NOT_FOUNDvalidationThe referenced certificate/listener resource does not exist.
HUAWEICLOUD_CONFLICTio_permanentName/state conflict — e.g. ambiguous name lookup matched multiple certificates.
HUAWEICLOUD_QUOTAio_transientAPI quota / rate limit hit.

F5 BIG-IP

CodeClassMeaning
F5BIGIP_CONNECTnetworkiControl REST unreachable.
F5BIGIP_AUTHauthAuthentication rejected.
F5BIGIP_UPLOADio_transientUploading cert/key files failed.
F5BIGIP_UPDATEio_transientUpdating objects (including the update transaction commit) failed.
F5BIGIP_NOT_FOUNDvalidationReferenced object does not exist.
F5BIGIP_CHAINio_transientInstalling the chain bundle failed.
F5BIGIP_OWNERSHIPio_permanentObject exists but is not managed by CertAutoPilot.
F5BIGIP_PROFILEio_permanentClient-SSL profile create/update failed.

HashiCorp Vault

CodeClassMeaning
VAULT_CONNECT_FAILEDnetworkVault unreachable.
VAULT_AUTH_FAILEDauthToken/AppRole authentication rejected.
VAULT_READ_FAILEDio_transientReading the existing secret failed.
VAULT_WRITE_FAILEDio_transientWriting the secret failed.
VAULT_VALIDATE_FAILEDvalidationPost-write validation of the stored material failed.
VAULT_PATH_INVALIDvalidationThe configured KV path is invalid.

Windows (generic WinRM)

CodeClassMeaning
WINRM_CONNECTnetworkWinRM endpoint unreachable.
WINRM_AUTHauthNTLM / 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_TIMEOUTio_transientCommand execution timed out.
WINRM_EXECio_transientActionSet command/script failed on the host.
WINRM_PS_SYNTAXvalidationThe PowerShell payload has a syntax error.
WINRM_FILEio_transientChunked file transfer / certutil decode failed.
WINRM_VALIDATIONvalidationValidationProfile check failed after deployment.
WINRM_QUOTAio_permanentWinRM quota exceeded (envelope size, concurrent shells).

Microsoft IIS

CodeClassMeaning
IIS_CONNECTnetworkWinRM connection or in-flight transport to the Windows host failed.
IIS_AUTHauth / validationNTLM / 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_FAILEDvalidation / io_transientBuilding the PKCS#12 bundle locally failed (validation — cert/key problem), or uploading it over WinRM failed (io_transient — retried).
IIS_IMPORT_FAILEDio_permanentImporting the PFX into the Windows certificate store failed, or the script result could not be parsed.
IIS_BINDING_NOT_FOUNDvalidationNo HTTPS binding matched the configured filter (or, in all_sites, no binding on any non-excluded site).
IIS_BINDING_AMBIGUOUSvalidationMore than one binding matched in single mode — refusing to guess.
IIS_BINDING_FAILEDio_permanentNo bindings could be updated (including the all-matched-bindings-are-CCS case).
IIS_APPPOOL_DETECT_FAILEDvalidationDetecting the application pools to recycle failed.
IIS_APPPOOL_RECYCLE_FAILEDio_permanentRecycling one or more application pools failed (run is partial).
IIS_VALIDATE_STOREvalidationPost-deploy check of the certificate store failed.
IIS_VALIDATE_BINDINGvalidation / io_transientPost-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_MISSINGvalidationA required server-side component (e.g. the WebAdministration PowerShell module) is missing.
IIS_SITE_NOT_FOUNDvalidationThe 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.

SMTP

The SMTP module classifies by SMTP reply code and sets the class directly on the result.

CodeClassMeaning
SMTP_CONNECTnetworkTCP dial / DNS failure before any SMTP conversation.
SMTP_TLSauthTLS handshake or certificate-trust failure (STARTTLS/SMTPS).
SMTP_AUTHauthAuthentication rejected (reply 530/534/535/538).
SMTP_TRANSIENTio_transientTemporary server condition (421/450/451/452/454, other 4xx, or unclassifiable errors).
SMTP_PERMANENTio_permanentPermanent rejection (550/552/554, other 5xx) — operator action needed.
SMTP_VALIDATIONvalidationThe request was malformed (500/501/503/553).
SMTP_PAYLOADvalidationBuilding the PEM / PKCS#12 attachment failed before sending.

AWS ACM

The AWS ACM module classifies AWS SDK errors itself, so one code can map to more than one class depending on the underlying cause.

CodeClassMeaning
AWS_CONNECTnetwork (dial/timeout) or io_transient (throttling)AWS API unreachable, or the request was throttled (Throttling, RequestLimitExceeded, TooManyRequests, SlowDown).
AWS_AUTHauthCredentials rejected (InvalidClientTokenId, SignatureDoesNotMatch, AccessDenied, UnauthorizedOperation, …).
AWS_CREDENTIALauthResolving the module credential for the target failed.
AWS_IMPORTvalidation (bad input, e.g. missing region) or io_permanent (import rejected)ImportCertificate failed or returned an unusable result.

Cloudflare

The certificate is uploaded to a Cloudflare zone as a Custom Certificate (Business/Enterprise plan) over the Cloudflare API; renewals update it in place.

CodeClassMeaning
CLOUDFLARE_CONNECTnetworkCloudflare API (api.cloudflare.com:443) unreachable — check egress/DNS and retry.
CLOUDFLARE_AUTHauthAPI token rejected — verify the token is active and carries Zone → SSL and Certificates → Edit on the target zone.
CLOUDFLARE_PLANvalidationThe zone's plan does not permit Custom Certificates — upgrade the zone to Business or Enterprise.
CLOUDFLARE_NOT_FOUNDvalidationThe referenced zone or custom certificate does not exist — check the zone ID / certificate ID.
CLOUDFLARE_CONFLICTvalidationMore than one custom certificate covers the hostname — pin an explicit certificate_id to disambiguate.
CLOUDFLARE_VALIDATIONvalidationThe request itself is invalid — bad bundle_method/type/geo_restrictions, or a cert/key the API rejected.
CLOUDFLARE_QUOTAio_transientAPI rate limit or custom-certificate quota hit — retried; if persistent, free a custom-cert slot or slow the cadence.

cPanel

CodeClassMeaning & resolution
CPANEL_CONNECTnetworkThe cPanel/WHM host is unreachable — check host, port, use_ssl and network egress; retried.
CPANEL_AUTHauthThe API token was rejected — verify username + token and the mode (cpanel vs whm).
CPANEL_NOT_FOUNDvalidationDomain or account not found on the server — verify the install domain(s) and, in WHM mode, the owning user.
CPANEL_CONFLICTvalidationThe domain is owned by a different account — set the correct whm_user.
CPANEL_VALIDATIONvalidationThe target spec is invalid — check host, mode and the domain list.
CPANEL_INSTALLio_permanentThe server rejected the install — check the certificate/key/chain and the domain ownership.
CPANEL_QUOTAio_transientRate limit exceeded — retried; if persistent, slow the cadence.

Azure Key Vault

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.

CodeClassMeaning
AZUREKV_CONNECTnetworkVault or AAD endpoint unreachable (also raised on an unexpected redirect) — check egress and the vault_url.
AZUREKV_AUTHauthToken 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_FOUNDvalidationVault or certificate not found — verify the vault URL and certificate name.
AZUREKV_CONFLICTvalidationA 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_VALIDATIONvalidationBad vault_url/cert_name, or Azure rejected the PFX.
AZUREKV_QUOTAio_transientKey Vault throttling (429) — retried automatically with backoff.

MerlinCDN

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).

CodeClassMeaning
MERLINCDN_CONNECTnetworkMerlinCDN API unreachable.
MERLINCDN_AUTHauthPersonal access token or org/workspace headers rejected.
MERLINCDN_NOT_FOUNDvalidationThe referenced distribution or canonical name does not exist.
MERLINCDN_CONFLICTio_permanentName/state conflict on the CDN.
MERLINCDN_QUOTAio_transientAPI quota / rate limit hit.
MERLINCDN_UPLOADio_permanentUploading the new certificate failed (nothing was bound).
MERLINCDN_BINDio_permanentRe-binding the canonical name to the new certificate failed; the just-uploaded cert is best-effort removed.

Exchange

On-premises Microsoft Exchange, deployed over WinRM + the Exchange Management Shell. Every renewal imports a new thumbprint (import → enable → optional remove-old).

CodeClassMeaning
EXCHANGE_CONNECTnetworkWinRM unreachable — host/port/network.
EXCHANGE_AUTHauthWinRM authentication rejected, or a TLS-verify / Kerberos misconfiguration (terminal).
EXCHANGE_EMS_UNAVAILABLEvalidationThe 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_MISSINGvalidationNo or malformed exchange_winrm credential (missing username/password).
EXCHANGE_IMPORTio_permanentImport-ExchangeCertificate failed.
EXCHANGE_ENABLEio_permanentEnable-ExchangeCertificate failed.
EXCHANGE_REMOVEio_permanentRemoving the previous certificate failed (it may still be in use).
EXCHANGE_NOT_FOUNDvalidationA referenced Exchange server or certificate was not found.
EXCHANGE_PFX_FAILEDvalidationBuilding the PKCS#12 from the cert/key failed.

PAN-OS

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.

CodeClassMeaning
PANOS_CONNECTnetworkTCP/TLS connection to the firewall management interface failed. Retried.
PANOS_AUTHauthAuthentication rejected (bad username/password or api_key, or an expired session key). Not retried. Note: username is required even with api_key.
PANOS_IMPORTio_transientThe 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_COMMITio_transientThe 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_FOUNDvalidationA referenced object does not exist on the firewall. Not retried.
PANOS_VALIDATIONvalidationThe device rejected the request as invalid (bad name, vsys set while multi-vsys is off, malformed input). Not retried.
PANOS_APIio_transientAn unclassified device-internal error. Retried.

See also