{"record":{"id":"0c1d7c6d9c653fb0","repo":"openai/codex","slug":"agents-max-concurrent-threads-per-session-must-be","errorCode":null,"errorMessage":"agents.max_concurrent_threads_per_session must be at least 1","messagePattern":"agents\\.max_concurrent_threads_per_session must be at least 1","errorType":"validation","errorClass":"std::io::Error","httpStatus":null,"severity":"error","filePath":"codex-rs/core/src/config/mod.rs","lineNumber":3756,"sourceCode":"        }\n        if multi_agent_v2.default_wait_timeout_ms > multi_agent_v2.max_wait_timeout_ms {\n            return Err(std::io::Error::new(\n                std::io::ErrorKind::InvalidInput,\n                \"features.multi_agent_v2.default_wait_timeout_ms must be at most features.multi_agent_v2.max_wait_timeout_ms\",\n            ));\n        }\n        validate_multi_agent_v2_tool_namespace(multi_agent_v2.tool_namespace.as_deref())?;\n        let agents_enabled = cfg\n            .agents\n            .as_ref()\n            .and_then(|agents| agents.enabled)\n            .unwrap_or(true);\n        let agent_max_threads = cfg\n            .agents\n            .as_ref()\n            .and_then(|agents| agents.max_concurrent_threads_per_session);\n        if agent_max_threads == Some(0) {\n            return Err(std::io::Error::new(\n                std::io::ErrorKind::InvalidInput,\n                \"agents.max_concurrent_threads_per_session must be at least 1\",\n            ));\n        }\n        let agent_max_depth = cfg\n            .agents\n            .as_ref()\n            .and_then(|agents| agents.max_depth)\n            .unwrap_or(DEFAULT_AGENT_MAX_DEPTH);\n        let agent_default_subagent_model = cfg\n            .agents\n            .as_ref()\n            .and_then(|agents| agents.default_subagent_model.clone());\n        let agent_default_subagent_reasoning_effort = cfg\n            .agents\n            .as_ref()\n            .and_then(|agents| agents.default_subagent_reasoning_effort.clone());\n        let agent_interrupt_message_enabled = cfg","sourceCodeStart":3738,"sourceCodeEnd":3774,"githubUrl":"https://github.com/openai/codex/blob/339751715c64496cb86246bfb3935f40e309dd3d/codex-rs/core/src/config/mod.rs#L3738-L3774","documentation":"The top-level `[agents]` table has its own concurrency limit. Only an explicit zero triggers the error (the check is agent_max_threads == Some(0)); an absent key passes and the default applies, so this always means someone wrote max_concurrent_threads_per_session = 0.","triggerScenarios":"`[agents]` with `max_concurrent_threads_per_session = 0` in any loaded layer, with agents enabled (or enabled unset, which defaults to true).","commonSituations":"Same mistake as the multi_agent_v2 twin of this knob: trying to disable subagents by zeroing the limit; stale tuned configs; managed layers zeroing the limit.","solutions":["Set `[agents]` `max_concurrent_threads_per_session` to 1 or higher.","Or remove the key to use the default.","To disable agents entirely, set `enabled = false` under `[agents]`."],"exampleFix":"# before\n[agents]\nmax_concurrent_threads_per_session = 0\n\n# after\n[agents]\nmax_concurrent_threads_per_session = 4\n\n# or disable agents instead\n# [agents]\n# enabled = false","handlingStrategy":"validation","validationCode":"import tomllib\nagents = tomllib.load(open(\"config.toml\", \"rb\")).get(\"agents\", {})\nlimit = agents.get(\"max_concurrent_threads_per_session\")\nassert limit is None or limit >= 1, \"agents.max_concurrent_threads_per_session must be >= 1\"","typeGuard":null,"tryCatchPattern":"match config_result {\n    Err(ref e) if e.kind() == std::io::ErrorKind::InvalidInput\n        && e.to_string().contains(\"agents.max_concurrent_threads_per_session\") => {\n        // clamp to 1 or drop the key, then retry\n    }\n    other => other,\n}","preventionTips":["Zero is not a valid concurrency limit in [agents] or [features.multi_agent_v2]","Use enabled = false to turn agents off","Validate both concurrency knobs in config pre-flight checks"],"tags":["codex","config","agents","validation"],"backgroundTag":"config-value-out-of-range","analyzedSha":"339751715c64496cb86246bfb3935f40e309dd3d","analyzedAt":"2026-08-25T05:35:09.876Z","schemaVersion":2},"datasetVersion":"2026-08-25T06:17:31.827Z"}