--json-schema flag: first invocation always fails, retry succeeds (cold-start pattern)
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 -psucceeds on first attempt every time - Schema content is correct — the same schema works fine on attempt 2
Additional Context
- When
claude -p --json-schemais 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-schemastructured 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-schemawith constrained decoding for guaranteed schema compliance in a multi-agent orchestration system. The workaround isMAX_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.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗