Skip to content

Deployment Backend Not Configured

URI: https://docs.ankatech.co/errors/deployment-backend-not-configured
HTTP Status: 409 Conflict

When you see this

A deployment key-protection backend operation was requested and there is no descriptor for it to act on. Nothing was sealed and no envelope row was written — a sealed value with no descriptor to own it is a secret nothing references, nothing evicts and nothing deletes.

Absence is not invalidity, and the two answer differently. No descriptor at all is this 409. A descriptor that exists and cannot produce a client is a 422 carrying DESCRIPTOR_INVALID. Reading one as the other sends an operator to correct coordinates that were never written.

It is reachable on every declarable backend family, not on the Cloud KMS families alone: the deployment plane admits the four PKCS#11 HSM tokens (softhsm, nshield, luna, cloudhsm) as well as the five Cloud KMS backends. But the two families reach it from different places, and the difference is what the resolution below turns on.

On a Cloud KMS family the ladder is configuration → credential → activate, and supplying a credential or activating before coordinates have been recorded is refused here.

On a PKCS#11 token there is no configuration step to omit. A declaration is completed by the platform at POST /api/v3/admin/platform/setup/backend/declare — it writes the descriptor itself — so reaching this refusal on that family means the declaration was never made, or was withdrawn.

What makes a declaration self-completing is a conjunction of THREE

The platform commits the descriptor at declare when the declared token accepts no endpoint, accepts no key coordinate, and its family seals no deployment credential. Only the four PKCS#11 tokens satisfy all three.

The first conjunct alone is true of six of the nine declarable tokens — the four PKCS#11 tokens and both Google tokens, which also accept no endpoint. So "the token accepts no endpoint" is not a description of this behaviour, and a gcp-kms or gcp-kms-hsm deployment still records its resource path through PUT /api/v3/admin/platform/setup/backend/configuration exactly as before.

A second declare replaces: the descriptor is re-derived from the newly declared token and the superseded projection is evicted first, so deployment_key_backend.backend_token always equals deployment_info.declared_backend, or there is no descriptor row at all.

Common Causes

  • PATCH /api/v3/admin/platform/setup/backend/credential was called before PUT /api/v3/admin/platform/setup/backend/configuration recorded the backend's coordinates.
  • POST /api/v3/admin/platform/setup/backend/activate was called on a Cloud KMS descriptor that carries no sealed credential.
  • POST /api/v3/admin/platform/setup/backend/activate was called on a deployment with no declared backend at all, or one whose declaration was withdrawn with DELETE /api/v3/admin/platform/setup/backend/declare. On a PKCS#11 token this is the only way to reach the refusal from activate: that family seals no deployment credential — its token PIN is the host's Docker Swarm secret at /run/secrets/pkcs11_pin — and it records no coordinates, so neither a missing credential nor a missing configuration can be the cause.

Response Example

{
  "type": "https://docs.ankatech.co/errors/deployment-backend-not-configured",
  "title": "Deployment Backend Not Configured",
  "status": 409,
  "detail": "No deployment key-protection backend is configured. Declare the deployment key-protection backend before this operation can act on it.",
  "instance": "/api/v3/admin/platform/setup/backend/credential",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "7e5c9014-2b6d-4a83-91f0-c48d5e7b2a63"
  }
}

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

How to Resolve

  1. Declare the backend with POST /api/v3/admin/platform/setup/backend/declare if nothing is declared. The detail says declare rather than record the coordinates deliberately: it is fixed and caller-independent, so it has to name a step every family performs, and four of the nine take no coordinates at all.
  2. On a Cloud KMS backend, record the coordinates with PUT /api/v3/admin/platform/setup/backend/configuration, then supply the credential with PATCH /api/v3/admin/platform/setup/backend/credential.
  3. On a PKCS#11 token, skip both of step 2. The declaration is already complete — the platform wrote the descriptor at declare — and there is nothing to record and no credential to seal. The TOKEN this deployment binds to is addressed separately, by the platform settings under Platform Settings → Cryptography & Trust → HSM / Cloud KMS, and it is hot-reloaded rather than recorded on this ladder. For an appliance the token itself is the operator’s, prepared on the host before the platform binds to it.

  4. Then activate with POST /api/v3/admin/platform/setup/backend/activate. This 409 carries no reason and no selfTest member because nothing was contacted, so there is nothing in the backend — cloud account or HSM partition — to investigate.

    A key coordinate submitted to a family that accepts none is a different refusal on a different type: 422 Backend Key Coordinate Requirement Not Satisfied. It is a deployment-plane type and not a byok- one, because on the per-tenant BYOK plane every family requires a coordinate and the refusal cannot occur.

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