Skip to content

License Schema Version Unsupported

URI: https://docs.ankatech.co/errors/license-schema-version-unsupported
HTTP Status: 422 Unprocessable Entity

When you see this

The license artifact declares a payload schema version this deployment does not support. The detail names both numbers — the version the artifact declares and the version this deployment admits.

This check runs before the composite signature is verified, so the declared version has not been authenticated when it is read. The detail therefore states only what was observed and deliberately asserts no cause — because at that point the service cannot distinguish the two causes below.

Common Causes

There are exactly two, and they call for different actions.

  • A version split — the artifact was signed by a signer built from a different ankasecure-common-license-contract release than the one this License Server was built from. Nothing is wrong with the file.
  • A tampered artifact — the version field of an otherwise well-formed artifact was edited. Since nothing has been authenticated at this point, an edited byte reaches this check too.

Response Example

{
  "type": "https://docs.ankatech.co/errors/license-schema-version-unsupported",
  "title": "Unsupported license schema version",
  "status": 422,
  "detail": "The license artifact declares schema version 2; this deployment supports version 1.",
  "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

First, tell the two causes apart — 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 — a version split. 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 identical refusal, so re-issuing alone never terminates.

If they are equal — a tampered artifact. Request a fresh artifact from ANKATech and install it without editing it. The artifact is signed as a whole; changing any field, including the version, invalidates it.

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