Invalid Instance State Transition

invalid-instance-state-transition · 409

An operator asked an instance for a move it can't make from the state it is in, so nothing changed.

Instances are run by Ghaym's operators through the admin routes. from is the state the instance is actually in, and to the one the call asked for.

Besides the members every error carries, this type adds instanceId, from and to.

Common causes

  • The instance was destroyed, and a start was asked for afterwards. A destroyed instance doesn't come back.
  • A start or a stop was asked for while an earlier one was still settling.

How to fix the call

  • Read the instance again and act on from.
  • Wait for a move to settle before asking for the next one.
  • To have a running instance after a destroy, create a new one.

Example response

json
{
  "type": "invalid-instance-state-transition",
  "title": "Invalid Instance State Transition",
  "detail": "Instance '0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401' cannot move from 'destroyed' to 'starting'",
  "instanceId": "0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401",
  "from": "destroyed",
  "to": "starting",
  "requestId": "req-1785231000000-4f7b2c9ae",
  "timestamp": "2026-07-28T09:30:00.000Z",
  "path": "/v1/admin/instances/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/start",
  "method": "POST",
  "instance": "POST /v1/admin/instances/0199e0a3-6f21-7c4a-9d18-2b7c5f3ad401/start",
  "status": 409,
  "docs": "https://ghaym.me/docs/errors/invalid-instance-state-transition"
}