--json-schema flag: first invocation always fails, retry succeeds (cold-start pattern)

Resolved 💬 3 comments Opened Feb 5, 2026 by johnsaddicted2LIVE Closed Feb 6, 2026

Bug Description

When using claude -p --json-schema '<schema>' "prompt" programmatically, the first invocation consistently fails (null output, exit code 1), but an immediate retry succeeds with correct structured output and turns_used: 1.

This is a reproducible cold-start pattern, not a transient failure.

Environment

  • CLI Version: 2.1.30 and 2.1.31 (tested both)
  • OS: macOS (Darwin 25.2.0)
  • Usage: Programmatic spawning via bash orchestrators (claude -p --json-schema)

Reproduction

# Attempt 1 — always fails (null output, exit 1, ~15-27s)
claude -p --json-schema '{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}' \
  "Return a greeting"

# Attempt 2 — succeeds (correct JSON, turns_used: 1, ~2-5s)  
claude -p --json-schema '{"type":"object","properties":{"answer":{"type":"string"}},"required":["answer"]}' \
  "Return a greeting"

Without --json-schema, claude -p "Return a greeting" works immediately on first attempt in 2-4s.

Evidence

We run parallel claude -p --json-schema spawns from bash orchestrators with retry logic and per-attempt I/O archiving. The pattern is consistent across dozens of invocations:

| Agent | Attempt 1 | Attempt 2 |
|-------|-----------|-----------|
| database-expert | null output, exit 1, 27s | 10KB response, 95% confidence, turns_used: 1 |
| aws-expert | null output, exit 1, 15s | 13KB response, 95% confidence, turns_used: 1 |
| streaming-expert | null output, exit 1, 22s | 2.8KB response, turns_used: 1 |
| auth-expert | null output, exit 1, 18s | null (timed out before attempt 2) |

Key observations:

  • Attempt 1 always fails regardless of schema complexity (tested with trivial 1-property schemas too)
  • Attempt 2 succeeds with turns_used: 1, proving it's not a turn budget issue
  • Without --json-schema, claude -p succeeds on first attempt every time
  • Schema content is correct — the same schema works fine on attempt 2

Additional Context

  • When claude -p --json-schema is invoked from inside a running Claude Code session (via Bash tool), it hangs indefinitely until timeout (exit 124). This may be a related but separate issue with nested CLI sessions.
  • The --json-schema structured output fix was introduced in v2.1.22 ("Fixed structured outputs for non-interactive (-p) mode"). The cold-start pattern may have been present since that initial implementation.
  • We use --json-schema with constrained decoding for guaranteed schema compliance in a multi-agent orchestration system. The workaround is MAX_RETRIES=1 (2 total attempts), which handles the cold-start reliably but doubles latency.

Expected Behavior

claude -p --json-schema '<schema>' "prompt" should succeed on first invocation, consistent with claude -p behavior without --json-schema.

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗