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"}
    }
  }
}

2. Re-enable one probe at a time.

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

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

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

5. 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 readiness, wave ordering, and service field details, see Configuration.