--- title: "PKI Express Return Codes" description: "Return codes of PKI Express operations, such as Ok, BadSyntax, UnknownError, FileNotFound and BadCertificate, with the meaning of each." canonical: "https://docs.lacunasoftware.com/en-us/articles/pki-express/return-codes" locale: "en" product: "PKI Express" last_updated: "2026-10-19" --- # PKI Express Return Codes The PKI Express operations have a set of return codes shown bellow with the meaning of each one. | Return Code | Meaning | |-------------------------------------|----------------------------------------------------------------------------------| | 00 - Ok | Operation completed successfully | | 01 - BadSyntax | Parameters do not match the expected format | | 02 - UnknownError | Unknown error | | 03 - FileNotFound | File not found | | 04 - BadCertificate | Error decoding certificate file | | 05 - BadThumbprint | Invalid thumbprint | | 06 - BadHash | Invalid To Sign Hash or could not infer the digest algorithm from the given hash | | 07 - BadData | Invalid To Sign Data | | 08 - BadSignature | Invalid Signature | | 09 - BadAlgorithm | Invalid Algorithm | | 10 - BadPolicy | Invalid Policy | | 11 - BadVisualRep | Error parsing visual representation parameters file | | 12 - UndefinedFileReference | Undefined file reference | | 13 - CertNotFound | Certificate not found | | 14 - ValidationFailed | Validation failed | | 15 - IOError | Error reading file | | 16 - NoCertsWithKey | PFX file does not contain any certificates with private key | | 17 - NotActivated | Not Activated PKI Express | | 18 - ActivationError | Fail to activate PKI Express | | 19 - BadLicense | Invalid Base-64 of activation license | | 20 - LicenseNeeded | No given license file | | 21 - InvalidLicense | Invalid license | | 22 - AccessDenied | Missing permission to modify PKI Express settings | | 23 - CertThumbNeeded | No given thumbprint | | 24 - BadPdfChanges | Error occurred while processing changes to PDF | | 25 - UpdateNeeded | Operation requires a newer version of PKI Express | | 26 - DataFileNeeded | No given Data File | | 27 - NoEncapsulatedContent | Missing encapsulated content | | 28 - NonceNotFound | Nonce not found | | 29 - DirectoryNotFound | Directory not found | | 30 - TimestampAuthorityNotAvailable | Timestamp requester failed | | 31 - PolicyRequiresNetwork | Chosen policy requires network (offline mode not supported) | | 32 - TimestampOptionsRequired | No given timestamp authority's address | | 33 - CultureNotFound | Culture not found | | 34 - TimeZoneNotFound | TimeZone not found | | 35 - InvalidUtcOffset | Invalid UTC offset | | 36 - KeySizeNotSupported | Unsupported key size | | 37 - BadKeyFormat | Unrecognized key format | | 38 - BadKey | Invalid key | | 39 - InvalidTimeoutValue | Invalid timeout value | | 40 - CertificateMismatch | Provided certificate file does not correspond to the stored key | | 41 - KeyNotFound | Key not found | | 42 - NoCertificateFile | No given certificate file | | 43 - BadCertificationLevel | Invalid certification level | ## Return codes in the client libraries The client libraries run PKI Express for each operation and turn any return code other than `00 - Ok` into an error. How you read the code depends on the language: | Language | A failed operation throws | How to read the return code | |---|---|---| | Java | `RuntimeException`, whose message holds the output of PKI Express | The exception does not carry the code | | Node.js | The promise rejects with `ValidationError` for `14 - ValidationFailed`, or else an error named `CommandError` | `err.code`; compare it with the exported `ErrorCodes`, such as `ErrorCodes.VALIDATION_FAILED` | | PHP | `CommandException`, with the message "The command failed with code *N*: *output*" | `$e->returnCode` | | Python | `Exception`, with the message "PKI Express returned non-success code *N*: *output*" | Only in the message | | Ruby | `PkiExpress::CommandError`, whose message holds the output of PKI Express | `e.code` is the `Process::Status` of the PKI Express process: read the number with `e.code.exitstatus` | When the library cannot find PKI Express, it throws `InstallationNotFoundException` (Java, PHP) or `InstallationNotFoundError` (Node.js, Python, Ruby) instead; see [client library settings](https://docs.lacunasoftware.com/en-us/articles/pki-express/config#client-library). When an operation needs a newer PKI Express than the one installed, the code is `01 - BadSyntax`; the Java, Node.js, PHP and Python libraries then end the message with a tip naming the version required (PHP then throws a plain `Exception`). In Node.js and Ruby, `ValidationError` and `InstallationNotFoundError` are subclasses of `CommandError`, so in Ruby one `rescue` covers them all; their `code` is a number: ```ruby begin signer.sign rescue PkiExpress::CommandError => e code = e.code.respond_to?(:exitstatus) ? e.code.exitstatus : e.code # code 14 (ValidationFailed): e.message has the validation results end ``` In PHP, catch `CommandException` (namespace `Lacuna\PkiExpress`) and read the code from its public `returnCode` property; catch `InstallationNotFoundException` separately, and the plain `Exception` last, since both exception classes extend it: ```php use Lacuna\PkiExpress\CommandException; use Lacuna\PkiExpress\InstallationNotFoundException; try { $signer->sign(); } catch (CommandException $e) { switch ($e->returnCode) { case 32: // TimestampOptionsRequired: set $signer->timestampAuthority break; case 14: // ValidationFailed: $e->getMessage() has the validation results break; default: // $e->getMessage(): "The command failed with code N: " throw $e; } } catch (InstallationNotFoundException $e) { // PKI Express was not found: see the client library settings } catch (Exception $e) { // Other errors, such as the tip asking for a newer PKI Express } ``` `CommandException` also has a public `cmd` property with the full command line the library ran. It includes the arguments, such as the password of a PKCS #12 file or a key, so don't write it to logs. ## Validation Errors Validation errors occur during signatures or authentications or inspections with validation. | Validation Error | Meaning | |-----------------------------------------|------------------------------------------------------------------------------------| | Success | Validation completed successfully | | CertificateNotYetValid | At the date reference, the certificate is not valid yet | | CertificateExpired | At the date reference, the certificate has expired | | CertificateRevoked | At the date reference, the certificate has been revoked | | CertificateIssuerNotFound | The issuer of the certificate could not be found | | CertificateRevocationStatusUnknown | The revocation status of the certificate could not be verify. Mostly, PKI Express could not access the certificate's CRLs (see [LAPP](https://docs.lacunasoftware.com/en-us/articles/pki-express/config/lapp)) | | CertificateChainRootNotTrusted | The root of the certificate chain is not trusted | | InvalidCertificateSignature | The signature is not valid based on the provided certificate's public key | | DecodeError | Could not decode a part of the object being validated | | RequiredSignedAttributeMissing | The signature does not have all required signed attributes | | ForbiddenSignedAttributePresent | The signature have one or more forbidden signed attributes | | RequiredUnsignedAttributeMissing | The signature does not have all required unsigned attributes | | ForbiddenUnsignedAttributePresent | The signature have one or more forbidden unsigned attributes | | ContentTypeMismatch | The content-type attribute specifies a different content-type than that of the CMS | | MessageDigestMismatch | The message digest attribute specifies a digest that does not match the digest of the signed data | | SigningCertificateDigestMismatch | The signing certificate attribute specifies a certificate digest that does not match the digest of the signer's certificate | | SignatureAlgorithmValidationFailed | The signature algorithm validation failed | | RevocationDataIssuedBeforeGracePeriod | The revocation data values were issued before the grace period | | UncertifiedDateReference | The date reference used to validate the signature is not certified | | SignaturePolicyMismatch | During validation, the signature policy differes from the given policy | | SigningTimeOutOfCertificateValidity | The signature happened out of the certificate validity period | | UnknownSignedAttributesPresent | The signature contains one or more unknown signed attributes | | UnknownUnsignedAttributesPresent | The signature contains one or more unknwon unsigned attributes | | TimestampWithMoreThanOneSigner | The timestamp has more than one signer | | TimestampMessageImprintMismatch | The timestamp message-imprint is not the same as the computed message-imprint | | CompleteReferencesMismatch | The certificate's complete reference is not valid | | InvalidSignatureTimestamp | The signature timestamp is not valid | | InvalidReferencesTimestamp | The reference timestamp is not valid | | InvalidSigAndRefsTimestamp | The signature timestamp and the reference timestamp is not valid | | InvalidArchiveTimestamp | The archive timestamp is not valid | | InvalidKeyUsage | The signing-certificate does not have permission for performing this type of operation | | InvalidOcspResponse | The OCSP's response is not valid | | UnauthorizedIssuer | The certificate issuer is not a CA | | UnknownRootTrustStatus | The root trust status is unknown | | InvalidTsl | The TSL is not valid | | InvalidCrl | The certificate CRLs are not valid | | CertificateIssuerValid | The certificate issuer is valid and trusted | | CertificateIssuerInvalid | The certificate issuer is not valid or not trusted | | CertificateValidationFailed | The certificate validation failed | | SignatureVulnerableToSignerSubstitution | The signature is vulnerable to signer substitution | | InvalidXmlSignatureSchema | The signature schema (XSD) is not valid | | XmlDSigCoreValidationFailed | The core validation of the signature failed (the digest or signature are incorrect) | | SignatureTimestampIgnored | The signature's timestamp was ignored | | InvalidCertificationPathLen | The CAs certification path is not valid | | SigningCertificateNotFound | The certificate of the signer was not found | | UnauthorizedACIssuer | The certificate issuer is a CA, therefore cannot be used to issue attribute certificates | | AlgorithmNotAllowed | The algorithm is not allowed | | UnacceptableSignaturePolicy | The signature policy is not acceptable | | TslNotAvailable | TSL is not available |