Skip to content

License Installation Identity Unavailable

URI: https://docs.ankatech.co/errors/license-installation-identity-unavailable
HTTP Status: 409 Conflict

When you see this

The licence server cannot establish which installation it is, so it refuses every operation that needs that identity. Nothing was written.

The installation ID is read from the installation's trial sentinel, a file the environment creation writes once and protects with an HMAC. The identity is unavailable when that sentinel is missing, unreadable, fails its integrity check, or carries no canonical installation ID. The licence server then fails closed rather than guess an identity:

  • the license import is refused with this problem;
  • Download activation request is refused with this problem;
  • the license read reports EXPIRED, carries no installationId, and no imported license is in force;
  • usage-statement reads and the statement verification keys are refused with this problem, and issuing a new statement is refused with usage-statement-coverage-unverifiable;
  • signed compliance evidence and its verification keys are refused with this problem, because the document's signature names the installation (Compliance Evidence).

Why 409

Nothing about the request is wrong. What fails is the state of the installation, and the same request succeeds once that state is repaired. A 5xx would reach you through the Admin API's relay as the licence server being unreachable.

Response Example

{
  "type": "https://docs.ankatech.co/errors/license-installation-identity-unavailable",
  "title": "Installation identity unavailable",
  "status": 409,
  "detail": "This installation's identity is unavailable: the deployment trial sentinel is missing, unreadable, fails its integrity check, or carries no canonical installation id. Restore the installation's sentinel, then retry.",
  "instance": "/api/v3/admin/platform/license/activation-request",
  "extensions": { "requestId": "2d8f4b6a-1c3e-4a7d-9b05-6e1f3a8c0d27" }
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. The detail names the condition and nothing about the sentinel's contents.

Raised by the License Server, relayed by the Admin API

The licence server 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. Restore the installation's trial sentinel (volumes/license-trial/deployment_trial.json) from the environment's backup, together with the trial HMAC secret it was written under. A backup restore carries both, because a restore is the same installation continuing.
  2. Do not write a new sentinel by hand, and do not recreate the environment to clear this. A new sentinel would carry a new installation ID, and every license issued for this installation would then be refused with license-installation-mismatch.
  3. Retry. No restart is needed; the sentinel is read on every request.

If no backup holds the sentinel, contact ANKATech support with the extensions.requestId; the installation needs a new license issued against a new activation request.

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

* restricted content — see higher-tier documentation