Skip to content

License Artifact Invalid

URI: https://docs.ankatech.co/errors/license-artifact-invalid
HTTP Status: 422 Unprocessable Entity

When you see this

The supplied license artifact (license.ankalic) failed validation — its structure or composite signature could not be verified, or it names a compliance pack the running release does not define.

Common Causes

  • A corrupted or truncated license artifact.
  • A license whose composite signature (ML-DSA-65 + Ed25519) does not verify.
  • A license file that was modified after signing.
  • A validity window the artifact model refuses — a missing validFrom or validTo, a validTo that falls before validFrom, or a negative gracePeriodDays. Such a license describes a term that is expired from its own start date, so it is refused before anything is verified. There is no maximum gracePeriodDays; only a negative one is refused.
  • An installation term the artifact model refuses — an installationId that is absent or not a lowercase canonical UUID, an environmentName that is absent or malformed, an absent licenseId, or an issuedAt that is absent or not in whole seconds. Refused before anything is verified; the detail names the component, never the value.
  • A signature.kid edited to name another trusted key — the kid is inside the bytes both signatures cover, so the signature no longer verifies. (A kid that names no trusted key at all is refused earlier, as License Signing Key Unknown.)
  • A compliance pack list that is not well formed — compliancePacks holds more than 64 entries, or an entry that is null or that is not upper case letters, digits and underscores (2 to 64 characters, starting with a letter). The artifact model refuses it before anything is verified, and the detail names the compliancePacks member, never the value.
  • A compliance pack this release does not define — the signature verifies, but compliancePacks names an identifier that is not one of the packs of the running release, typically a licence issued under an earlier pack vocabulary. The refusal comes after signature verification and before anything is stored; the detail names the compliancePacks member, never the value, and says to re-issue the licence. See Compliance Packs.
  • A version split — the signing tool and the License Server were built from different ankasecure-common-license-contract releases. This is the one cause that a freshly-issued artifact does not fix; see "If a freshly-issued artifact fails identically" below.

Response Example

{
  "type": "https://docs.ankatech.co/errors/license-artifact-invalid",
  "title": "Invalid license artifact",
  "status": 422,
  "detail": "The license artifact was rejected: it is not a well-formed license artifact, or its composite signature did not verify.",
  "instance": "/api/v3/admin/platform/license/import",
  "extensions": { "requestId": "8b0c2d4e-6f1a-4b3c-9d5e-2a7f8c1b0d3e" }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details.

Read the detail — a refused validity window says which component was wrong

The generic detail above covers the four routes inside the import service. A license whose validity window the artifact model refuses carries a different detail under the same type, naming the offending component and nothing else — the supplied value is never echoed back:

{
  "type": "https://docs.ankatech.co/errors/license-artifact-invalid",
  "title": "Invalid license artifact",
  "status": 422,
  "detail": "License payload validTo must not be before validFrom.",
  "instance": "/api/v3/admin/platform/license/import",
  "extensions": { "requestId": "8b0c2d4e-6f1a-4b3c-9d5e-2a7f8c1b0d3e" }
}

That distinction is worth acting on: a named component means the license file's term is wrong and re-obtaining the same file will not help — it needs re-issuing with a corrected window.

The two compliance-pack causes above follow the same rule. Their detail names the compliancePacks member and never the identifier supplied, and a pack the running release does not define is answered only after the signature has verified, so it is never a statement about a file that was tampered with. Either way the remedy is a licence re-issued with the current pack identifiers.

Raised by the License Server, relayed by the Admin API

The import is POST /api/v3/admin/platform/license/import on the Admin API, which forwards the artifact to the licence server over a service-to-service call; the licence server is the only validator of the artifact and raises this refusal. The Admin API relays its type, title, detail and status unchanged and sets its own instance and extensions.requestId. Correlate a request by extensions.requestId.

How to Resolve

  1. If the detail names compliancePacks, have the licence re-issued with the current pack identifiers and import the new one; the rest of this list does not apply.
  2. Confirm the license artifact was not modified after it was issued.
  3. Re-obtain the license artifact from ANKATech and replace the existing one.
  4. If a freshly-issued artifact fails identically, stop re-obtaining it and follow the section below.

If a freshly-issued artifact fails identically

Re-obtaining the artifact reproduces the same bytes, so repeating step 3 cannot converge. The remaining cause is a version split: the signature is computed over a canonical serialization of the payload produced by the shared ankasecure-common-license-contract library, and signer/verifier byte-parity holds only while both sides resolve the same build of it. Two builds whose canonicalization differs produce different signature preimages for a semantically identical payload — so the signature legitimately fails to verify on an artifact nobody altered.

Report it rather than diagnosing it further. Contact ANKATech support with:

  1. The extensions.requestId from the failed import's problem body.
  2. The full application/problem+json body.
  3. The version reported by the running License Server, and the date the artifact was issued.

A version split is resolved on the ANKATech side and by an upgrade of the License Server; it is not something a re-issued artifact, an edit to the file, or any change you can make on the deployment will clear. Support will tell you which of the two it is and what to install.

A version split that also moved the payload schema version is refused earlier and more precisely, as License Schema Version Unsupported. A split that changed the canonical bytes without changing the schema version surfaces here instead.

For full schema definitions, examples, and interactive testing, see the Developer Hub Reference.