Skip to content

Deployment Backend Declaration Is In A Retired Shape

URI: https://docs.ankatech.co/errors/key-backend-descriptor-retired-shape
HTTP Status: 409 Conflict

When you see this

The deployment's stored key-protection declaration was written in a shape this build no longer reads, so the operation could not be performed against it. Nothing was written, nothing was contacted, and the state of the deployment is exactly what it was before the call.

This is a state of the deployment, not of your request. An identical retry produces an identical response, which is why no Retry-After header is sent.

Common Causes

There is one cause. A platform release collapsed the members of the stored deployment descriptor, and the reader rejects unknown members by design rather than best-effort mapping them onto the new shape. A declaration persisted before that release therefore stops deserializing, and nothing rewrites it on the deployment's behalf — the platform carries no dual reader and no migration path.

The condition can only exist in a deployment that was already carrying a bound cloud backend across that upgrade. A deployment provisioned on the current release is born in the current shape and cannot reach this state.

How to Resolve

  1. Do not retry on a timer. Nothing about the condition changes between attempts.
  2. Report it to whoever operates the deployment, quoting the correlationId or requestId from the response body.
  3. An operator resolves it by recreating the environment and declaring the backend again on the fresh environment. Re-pointing the coordinates in place is refused: once a backend is bound and wrapped key material exists, the platform's immutability gate answers 409 to both write paths, because re-pointing bound coordinates would orphan that material.

The related read does not fail. GET /api/v3/admin/platform/setup/backend/configuration deliberately absorbs this refusal and answers 200 with a null configuration beside a FAILED / DESCRIPTOR_INVALID self-test, so an operator console can still render the backend screen and show what is wrong. Only the operating callers propagate the 409.

For API clients: this response carries the extension member backendType, naming the declared backend token. It carries no coordinate — no endpoint, resource path, ARN, vault URL, region or account id.

Where it is raised

Three operating paths read the stored declaration and let this refusal reach the caller. The first two act on the declaration itself. The third acts on it while establishing a tenant's key-encryption key — which is why this response can reach an operator who was not on the backend screen at all.

  • POST /api/v3/admin/platform/setup/backend/activate
  • PATCH /api/v3/admin/platform/setup/backend/credential
  • Any operation that must provision a tenant's key-encryption key from the deployment declaration. The declaration is read to establish that key, so an unreadable row refuses the operation that needed it, with this same type. Three reach it: POST /api/v3/admin/tenants/{tenantId}/keys (the first key created for a tenant that has none yet), the just-in-time tenant resolve behind the marketplace ingress, and enrolling a second factor for a user in such a tenant.

Provisioning a tenant does NOT reach it. POST /api/v3/admin/platform/tenants/provision deliberately defers the per-tenant key-encryption key to the first key operation, so tenant administration continues to work while the key-material backend is unusable. The refusal surfaces at the first operation that actually needs the key, not at the tenant's creation.