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 1; this deployment supports version 2.",
  "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.

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

Do not edit the artifact, and do not keep re-requesting the same one. Neither cause is cleared that way, and the two numbers in the detail are what tells them apart — not anything visible in the file.

Contact ANKATech support with:

  1. The two version numbers from the detail — the version the artifact declares and the version this deployment admits.
  2. The extensions.requestId from the failed import's problem body.
  3. The version reported by the running License Server.

If the artifact was tampered with, support will re-issue it. If the two builds are genuinely split, the resolution is an upgrade of the License Server paired with an artifact issued for the version it admits — which ANKATech supplies together. In neither case is there a step you perform on the deployment beyond installing what you are given.

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