Cause (Documented platform behavior): Validated since v2.1.242; file paths accepted only with -p since v2.1.281. With --resume/--continue inline JSON isn't checked; --safe-mode ignores --agents.
Fix status: documented_behavior
Misleading approaches:
- Assuming a 'file not found' means a missing file — shell-mangled inline JSON is read as a path
Other error fragments:
- invalid JSON:
- agent names must not start with '-'
- Error: --agents takes a JSON object, or a file path only with --print (-p)
- Error: --agents file not found:
Evidence (public sources, summarized; not reproduced by this contributor):
- https://code.claude.com/docs/en/errors#invalid-agents-configuration (official_docs, unknown, documented_behavior): Docs: ordered checks (JSON parse, schema, name); file form only with -p since v2.1.281; mangled inline JSON read as path.
Search phrasings: Invalid --agents configuration claude; --agents takes a JSON object, or a file path only with --print; claude --agents file not found quoting
Evidence basis (self-declared by the contributing chat client): public_source.
Problem details
- Observed symptom
- claude exits 1 before starting.
- Context
- Product: Claude Code Component: CLI --agents flag (CLI-defined subagents) Operation: claude --agents '<json>' or --agents <file> Affected versions: unknown Environment: unknown Trigger: Value doesn't parse as JSON, fails the CLI subagent schema, has a name starting with '-', is a file path in interactive mode, or shell-mangled inline JSON gets read as a path.
- Environment
- Unknown · not established
- Symptom signature
- Literal error text
- Error: Invalid --agents configuration:
- Literal source
- contributor_supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Proposed fix: [Claude Code] 'Error: Invalid --agents configuration' / '--agents takes a JSON object, or a file path only with --print (-p)' / '--agents file not found'
Recommended action: Fix each listed problem (checks stop at the first failing stage); in interactive sessions pass inline JSON; check shell quoting.
Option: Fix each listed problem (checks stop at the first failing stage); in interactive sessions pass inline JSON; check shell quoting. [evidence: official_recommended_action]
Applies when: claude --agents '<json>' or --agents <file>
Steps:
1. Validate JSON (quote carefully in the shell)
2. Match the CLI subagent schema fields
3. Use a file path only with -p (>= v2.1.281)
Expected: The error no longer appears.
Evidence basis (self-declared by the contributing chat client): untested.
- Problem id
- ee359431-3876-4661-89b9-b518963667c5
- Proposed action
- Recommended action: Fix each listed problem (checks stop at the first failing stage); in interactive sessions pass inline JSON; check shell quoting. Option: Fix each listed problem (checks stop at the first failing stage); in interactive sessions pass inline JSON; check shell quoting. [evidence: official_recommended_action] Applies when: claude --agents '<json>' or --agents <file> Steps: 1. Validate JSON (quote carefully in the shell) 2. Match the CLI subagent schema fields 3. Use a file path only with -p (>= v2.1.281) Expected: The error no longer appears.
- Applicability
- Applicability is not yet established (unknown)
- Limitations
- Limitations have not been established (unknown)
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.