Skip to content

Deployment Backend Unreachable

URI: https://docs.ankatech.co/errors/deployment-backend-unreachable
HTTP Status: 503 Service Unavailable

When you see this

The deployment key-protection backend could not be addressed at all with the configuration recorded for it — and, on the Cloud KMS families, the credential sealed for it — so no client could be built and no request ever left the platform. The response carries a Retry-After header and nothing was changed. The underlying cause is retained for server logs only and is never rendered, because every cloud SDK puts the account URL, the resource path, the region and the account id into its exception text.

It is reachable on every declarable backend family. The deployment plane addresses the four PKCS#11 HSM tokens (softhsm, nshield, luna, cloudhsm) as well as the five Cloud KMS backends, and a PKCS#11 token this platform cannot open answers here too.

Common Causes

  • The recorded descriptor is incomplete, or carries no configuration at all.
  • The sealed credential could not be unsealed or decoded (Cloud KMS families only).
  • The credential belongs to a different provider family than the declared backend (Cloud KMS families only).
  • On a PKCS#11 token: the module named by PKCS11_MODULE_PATH could not be loaded, the token coordinate resolved by the platform-settings plane names no reachable token, or the PIN at /run/secrets/pkcs11_pin is absent. This family seals no deployment credential, so a credential fault is never the cause here.

Response Example

{
  "type": "https://docs.ankatech.co/errors/deployment-backend-unreachable",
  "title": "Deployment Backend Unreachable",
  "status": 503,
  "detail": "The deployment key-protection backend could not be addressed with the configuration and credential recorded for it. Nothing was changed.",
  "instance": "/api/v3/admin/platform/setup/backend/activate",
  "timestamp": 1730000000,
  "extensions": {
    "requestId": "0a3d7c81-6e24-4b95-a0f7-92c15d84e3b6"
  }
}

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

How to Resolve

  1. Re-read the recorded coordinates with GET /api/v3/admin/platform/setup/backend/configuration and confirm the declared backend token and every coordinate the family requires.
  2. On a Cloud KMS backend, confirm the credential you supplied belongs to the same provider family as the declared backend, then re-submit it with PATCH /api/v3/admin/platform/setup/backend/credential. On a PKCS#11 token there is no credential step: check the token coordinates in the console instead, under Platform Settings → Cryptography & Trust → HSM / Cloud KMS, where PKCS11_TOKEN_SELECT_BY, PKCS11_TOKEN_LABEL and PKCS11_TOKEN_SERIAL live. They are hot-reloaded, so no redeploy is needed. Selection by slot index is not resolvable on the deployment plane: a PKCS11_TOKEN_SELECT_BY of index is refused at resolution time, so select by label or serial — by label on AWS CloudHSM, whose module reports no token serial, so serial is refused there at the write (Token Serial Not Reported By The Declared Backend).
  3. Rehearse with POST /api/v3/admin/platform/setup/backend/validate before activating again.

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