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.

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.	No
auth	SSH/API authentication failure, credential rejected.	No
validation	Cert/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

Code	Class	Meaning
CREDENTIAL_MISSING	auth	The module credential referenced by the target could not be resolved.

SSH

Code	Class	Meaning
SSH_CONNECT	network	TCP/SSH connection to the target failed.
SSH_AUTH	auth	SSH authentication rejected (key or password).
SFTP_FAILED	io_transient	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.

Webhook

Code	Class	Meaning
WEBHOOK_CONNECT	network	The webhook endpoint could not be reached.
WEBHOOK_NON_2XX	io_transient	The endpoint answered with a non-2xx HTTP status.

Kubernetes

Code	Class	Meaning
K8S_CONNECT	network	The API server could not be reached.
K8S_FORBIDDEN	auth	RBAC denied the secret create/update.
K8S_NOT_FOUND	validation	Namespace or referenced object does not exist.
K8S_APPLY_FAILED	io_transient	Applying the Secret failed for another reason.

NetScaler

Code	Class	Meaning
NETSCALER_CONNECT	network	NITRO API unreachable.
NETSCALER_AUTH	auth	NITRO login rejected.
NETSCALER_UPLOAD	io_transient	Uploading the cert/key files failed.
NETSCALER_UPDATE	io_transient	Updating the certkey object failed.
NETSCALER_NOT_FOUND	validation	The certkey / vserver referenced does not exist.
NETSCALER_LINK	io_transient	Linking the certificate to the CA chain failed.
NETSCALER_CHAIN	io_transient	Installing the chain certificate failed.
NETSCALER_OWNERSHIP	io_permanent	The object exists but is not managed by CertAutoPilot — refusing to overwrite.

Huawei Cloud

Code	Class	Meaning
HUAWEICLOUD_CONNECT	network	Huawei Cloud API unreachable.
HUAWEICLOUD_AUTH	auth	AK/SK authentication rejected.
HUAWEICLOUD_NOT_FOUND	validation	The referenced certificate/listener resource does not exist.
HUAWEICLOUD_CONFLICT	io_permanent	Name/state conflict — e.g. ambiguous name lookup matched multiple certificates.
HUAWEICLOUD_QUOTA	io_transient	API quota / rate limit hit.

F5 BIG-IP

Code	Class	Meaning
F5BIGIP_CONNECT	network	iControl REST unreachable.
F5BIGIP_AUTH	auth	Authentication rejected.
F5BIGIP_UPLOAD	io_transient	Uploading cert/key files failed.
F5BIGIP_UPDATE	io_transient	Updating objects (including the update transaction commit) failed.
F5BIGIP_NOT_FOUND	validation	Referenced object does not exist.
F5BIGIP_CHAIN	io_transient	Installing the chain bundle failed.
F5BIGIP_OWNERSHIP	io_permanent	Object exists but is not managed by CertAutoPilot.
F5BIGIP_PROFILE	io_permanent	Client-SSL profile create/update failed.

HashiCorp Vault

Code	Class	Meaning
VAULT_CONNECT_FAILED	network	Vault unreachable.
VAULT_AUTH_FAILED	auth	Token/AppRole authentication rejected.
VAULT_READ_FAILED	io_transient	Reading the existing secret failed.
VAULT_WRITE_FAILED	io_transient	Writing the secret failed.
VAULT_VALIDATE_FAILED	validation	Post-write validation of the stored material failed.
VAULT_PATH_INVALID	validation	The configured KV path is invalid.
VAULT_ROLLBACK_FAILED	io_transient	KV v2 version-restore during rollback failed.

Windows (generic WinRM)

Code	Class	Meaning
WINRM_CONNECT	network	WinRM endpoint unreachable.
WINRM_AUTH	auth	NTLM / Basic / Kerberos authentication rejected.
WINRM_TIMEOUT	io_transient	Command execution timed out.
WINRM_EXEC	io_transient	ActionSet command/script failed on the host.
WINRM_PS_SYNTAX	validation	The PowerShell payload has a syntax error.
WINRM_FILE	io_transient	Chunked file transfer / certutil decode failed.
WINRM_VALIDATION	validation	ValidationProfile check failed after deployment.
WINRM_QUOTA	io_permanent	WinRM quota exceeded (envelope size, concurrent shells).

Microsoft IIS

Code	Class	Meaning
IIS_CONNECT	network	WinRM connection or in-flight transport to the Windows host failed.
IIS_AUTH	auth	NTLM/Basic authentication rejected, or the account lacks store/binding permissions.
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.

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.

Code	Class	Meaning
SMTP_CONNECT	network	TCP dial / DNS failure before any SMTP conversation.
SMTP_TLS	auth	TLS handshake or certificate-trust failure (STARTTLS/SMTPS).
SMTP_AUTH	auth	Authentication rejected (reply 530/534/535/538).
SMTP_TRANSIENT	io_transient	Temporary server condition (421/450/451/452/454, other 4xx, or unclassifiable errors).
SMTP_PERMANENT	io_permanent	Permanent rejection (550/552/554, other 5xx) — operator action needed.
SMTP_VALIDATION	validation	The request was malformed (500/501/503/553).
SMTP_PAYLOAD	validation	Building 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.

Code	Class	Meaning
AWS_CONNECT	network (dial/timeout) or io_transient (throttling)	AWS API unreachable, or the request was throttled (Throttling, RequestLimitExceeded, TooManyRequests, SlowDown).
AWS_AUTH	auth	Credentials rejected (InvalidClientTokenId, SignatureDoesNotMatch, AccessDenied, UnauthorizedOperation, …).
AWS_CREDENTIAL	auth	Resolving the module credential for the target failed.
AWS_IMPORT	validation (bad input, e.g. missing region) or io_permanent (import rejected)	ImportCertificate failed or returned an unusable result.

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

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.

See also

• Distribution overview
• Fan-out execution & per-target retry
• Rollback support by module
• Job types