Skip to main content

Readiness Stuck

Symptoms​

  • a daemon stays in starting or running and never reaches ready
  • dependent services do not start
  • startup appears frozen even though a process exists

Likely causes​

  • ready.type does not match how the service becomes usable
  • ready.type: "http" uses a wrong URL or returns non-2xx/3xx
  • ready.type: "tcp" points to the wrong port
  • service is listening on another interface/port than configured
  • dependency graph waits on a readiness gate that never passes

Resolution​

  1. Temporarily disable readiness to isolate pure process startup:
{
  "services": {
    "api": {
      "cmd": ["go", "run", "./cmd/api"],
      "ready": {"type": "none"}
    }
  }
}

  1. Re-enable one probe at a time.

  2. For HTTP readiness, test the exact URL manually:

curl -i http://127.0.0.1:3000/healthz

  1. For TCP readiness, ensure ready.port or service.port matches the real listener.

  2. Keep dependsOn only for hard runtime requirements. Extra edges create unnecessary blocking.

Important behavior​

  • Daemon services with readiness gates block later waves until probe success.
  • Oneshot services wait for exit code 0; readiness probing can continue asynchronously.
  • There is no user-configurable readiness timeout knob in current schema.

For field details, see Readiness and Waves.