Skip to content

Instance Claim Code Invalid

URI: https://docs.ankatech.co/errors/instance-claim-code-invalid
HTTP Status: 400 Bad Request

When you see this

The console's claim screen sent a claim code that does not redeem. A new environment holds no platform administrator; the operator of the environment host mints a single-use claim code with envctl.sh <env> claim-code, and the person who enters it on the claim screen, with an e-mail address, becomes the first platform administrator. This code was not accepted, so nothing was created and the sign-in did not start.

Every case below answers the same body, so the answer does not tell them apart, and in particular never tells whether the instance is already claimed. The console shows "This claim code cannot be used" with "Ask the operator of this installation for a new code, or sign in if the installation is already set up."

Common Causes

  • No claim code was minted for this environment yet.
  • The code is not the one outstanding: a later claim-code run replaced it.
  • The code is more than one hour old.
  • The code was already redeemed, and it is entered with a different e-mail address than the one it claimed for. Five such attempts invalidate the code.
  • The code was copied incompletely: a claim code is 43 base64url characters.
  • The instance is already claimed: every claim start but the retry of the founder's own claim (step 3 below) gets this answer.

Response Example

{
  "type": "https://docs.ankatech.co/errors/instance-claim-code-invalid",
  "title": "Instance Claim Code Invalid",
  "status": 400,
  "detail": "The claim code is not valid. Mint a new one on the environment host with envctl.sh <env> claim-code and enter it within one hour. Nothing was created.",
  "instance": "/api/v3/auth/authorize-challenge",
  "timestamp": 1792236600
}

Content-Type: application/problem+json — the response follows RFC 9457 Problem Details. This is an Auth API body, so it carries no correlation member: correlate through the X-Correlation-Id response header. See Error Index & Overview.

How to Resolve

  1. On the environment host, mint a new code:

    sudo /opt/ankatech/admin/envctl.sh <env> claim-code

  2. Enter it on the claim screen within one hour, with the e-mail address of the first platform administrator.

  3. If a claim started with this code and its reply was lost, enter the same code with the same e-mail address again: the claim continues, and no second administrator is created.
  4. If the installation is already set up, sign in instead. claim-code tells the operator so: on a claimed instance it is refused instance-already-claimed.

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

* restricted content — see higher-tier documentation