{"record":{"id":"889a0720e2b22a6d","repo":"Hmbown/CodeWhale","slug":"sub-agent-state-file-exceeds-the-16-mib-limit","errorCode":null,"errorMessage":"sub-agent state file {} exceeds the 16 MiB limit","messagePattern":"sub-agent state file (.+?) exceeds the 16 MiB limit","errorType":"validation","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"crates/tui/src/tools/subagent/mod.rs","lineNumber":8929,"sourceCode":"\nfn read_subagent_state_file(state_root: &Path, path: &Path) -> Result<String> {\n    let state_root = normalize_subagent_workspace(state_root);\n    reject_root_relative_symlinks(&state_root, path)?;\n    let metadata = fs::symlink_metadata(path)?;\n    let file_type = metadata.file_type();\n    if file_type.is_symlink() || !file_type.is_file() {\n        return Err(anyhow!(\n            \"sub-agent state path must be a regular file: {}\",\n            path.display()\n        ));\n    }\n\n    let file = open_subagent_state_file(path)?;\n    let mut raw = String::new();\n    file.take(MAX_SUBAGENT_STATE_BYTES + 1)\n        .read_to_string(&mut raw)?;\n    if raw.len() as u64 > MAX_SUBAGENT_STATE_BYTES {\n        return Err(anyhow!(\n            \"sub-agent state file {} exceeds the 16 MiB limit\",\n            path.display()\n        ));\n    }\n    Ok(raw)\n}\n\n#[cfg(unix)]\nfn open_subagent_state_file(path: &Path) -> Result<fs::File> {\n    use std::os::unix::fs::OpenOptionsExt;\n\n    fs::OpenOptions::new()\n        .read(true)\n        .custom_flags(libc::O_NOFOLLOW)\n        .open(path)\n        .map_err(Into::into)\n}\n","sourceCodeStart":8911,"sourceCodeEnd":8947,"githubUrl":"https://github.com/Hmbown/CodeWhale/blob/73e0f67d83c59909b571efdfc88c4bc28c309cb1/crates/tui/src/tools/subagent/mod.rs#L8911-L8947","documentation":"The sub-agent tool loads its persisted state file from disk and enforces a hard 16 MiB cap (MAX_SUBAGENT_STATE_BYTES) so a corrupted or runaway state file cannot exhaust memory. Before the limit test it reads MAX_SUBAGENT_STATE_BYTES + 1 bytes via file.take(...), so any file larger than the cap is detected. When the byte count exceeds the cap, open fails with this anyhow error instead of returning the content.","triggerScenarios":"Calling the sub-agent state load path (open/read of the state file) when the file on disk is larger than 16 MiB; also occurs when the file is exactly at the boundary because one extra byte is read to detect overflow.","commonSituations":"Long-lived agents accumulating state across many sessions, a crashed writer leaving a bloated or truncated-corrupted state file, or the state root being pointed at the wrong directory so a huge unrelated file sits at the expected path.","solutions":["Inspect the state file size (ls -lh) and delete or archive the oversized state file so a fresh one is written","Find what is bloating the state (large task payloads, accumulated results) and narrow/paginate what gets persisted","Point the sub-agent state root at the correct dedicated directory instead of one containing large files","Raise MAX_SUBAGENT_STATE_BYTES in crates/tui/src/tools/subagent/mod.rs only if your workload genuinely needs more state"],"exampleFix":"// before: blindly loading state\nlet state = load_subagent_state(&path).await?;\n// after: check size first and reset if over limit\nif fs::metadata(&path)?.len() > 16 * 1024 * 1024 {\n    fs::remove_file(&path)?; // start a fresh state file\n}\nlet state = load_subagent_state(&path).await?;","handlingStrategy":"validation","validationCode":"let max = 16 * 1024 * 1024;\nif let Ok(meta) = std::fs::metadata(&state_path) {\n    if meta.len() > max { std::fs::remove_file(&state_path).ok(); }\n}","typeGuard":"fn state_file_within_limit(path: &Path, max: u64) -> bool {\n    std::fs::metadata(path).map(|m| m.len() <= max).unwrap_or(false)\n}","tryCatchPattern":"match load_subagent_state(&path) {\n    Ok(raw) => raw,\n    Err(e) if e.to_string().contains(\"16 MiB\") => {\n        std::fs::remove_file(&path).ok();\n        Default::default() // fresh state\n    }\n    Err(e) => return Err(e),\n}","preventionTips":["Cap what gets persisted into sub-agent state at write time","Monitor state file sizes and rotate when approaching 16 MiB","Keep the state root dedicated to sub-agent state, not shared directories"],"tags":["subagent","file-size-limit","state-file"],"backgroundTag":"file-size-limit-exceeded","analyzedSha":"73e0f67d83c59909b571efdfc88c4bc28c309cb1","analyzedAt":"2026-09-22T01:30:00.501Z","contentChangedAt":"2026-09-22T01:30:00.501Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}