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.

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 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/licenses/deployment/import"
}

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

The License Server's problem bodies carry no extension members

The five RFC-defined members above are the whole body. The License Server's import exception handler builds a plain Spring ProblemDetail and sets only type, title, status and detail (instance is filled in from the request), so — unlike Core API, which carries a top-level correlationId, or Admin API and Audit API, which nest a requestId under extensions — this service emits no correlation member in the body at all. Correlate a request by the X-Correlation-Id response header.

How to Resolve

  1. Confirm the license artifact was not modified after it was issued.
  2. Re-obtain the license artifact from ANKATech and replace the existing one.
  3. 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 2 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.

Distinguish it by comparing the two builds, not by inspecting the file:

  1. Read the ankasecure-common-license-contract version bundled by the signing tool that produced the artifact.
  2. Read the ankasecure-common-license-contract version bundled by the running License Server.

If they differ, the terminating remedy is: rebuild the signer and the License Server from a single ankasecure-common-license-contract build, redeploy the License Server, then re-issue the artifact from that signer. Both halves are required — re-issuing from an unrebuilt signer reproduces the same failure.

If they are equal, the artifact really was corrupted, truncated, or modified. Contact support with the X-Correlation-Id response header value (this service does not echo a correlation member in the body — see the note above).

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.