zeroclaw-labs/zeroclaw · warning · DiagItem

[{alias}] {name} not found (optional)

Error message

[{alias}] {name} not found (optional)

What it means

A `zeroclaw doctor` warning from `check_agent_file` (via `check_workspace`): an optional per-agent workspace file — `SOUL.md` or `AGENTS.md` — is missing from the agent's workspace directory (`config.agent_workspace_dir(alias)`) for an enabled agent. The `(optional)` suffix is deliberate: the agent runs without it, but the persona/instruction layer doctor expects is absent. Items are prefixed `[alias]` so multi-agent reports stay legible.

Source

Thrown at crates/zeroclaw-runtime/src/doctor/mod.rs:1545

        check_agent_file(&agent_ws, "AGENTS.md", alias, cat, items);
    }
}

/// Existence check for an optional per-agent workspace file. Prefixes the
/// owning agent alias as `[alias]` so a multi-agent report stays legible and
/// `(optional)` keeps its single, consistent meaning as the severity hint
/// (e.g. `[default] SOUL.md present`, `[default] AGENTS.md not found (optional)`).
fn check_agent_file(
    workspace_dir: &Path,
    name: &str,
    alias: &str,
    cat: &'static str,
    items: &mut Vec<DiagItem>,
) {
    if workspace_dir.join(name).is_file() {
        items.push(DiagItem::ok(cat, format!("[{alias}] {name} present")));
    } else {
        items.push(DiagItem::warn(
            cat,
            format!("[{alias}] {name} not found (optional)"),
        ));
    }
}

fn disk_available_mb(path: &Path) -> Option<u64> {
    let output = std::process::Command::new("df")
        .arg("-m")
        .arg(path)
        .output()
        .ok()?;
    if !output.status.success() {
        return None;
    }
    let stdout = String::from_utf8_lossy(&output.stdout);
    parse_df_available_mb(&stdout)
}

View on GitHub (pinned to 88bb9c8533)

Solutions

1. If you want the persona/instruction layer, create the named file in the agent's workspace directory (the one `zeroclaw doctor` reports against).
2. Re-run `zeroclaw doctor` to confirm the item flips to `[alias] SOUL.md present`.
3. If the file is intentionally absent, ignore the warning — it is explicitly marked optional.

Example fix

# before: agent workspace has no SOUL.md
# doctor: [default] SOUL.md not found (optional)

# after
printf '# Persona\nYou are a concise, helpful assistant.\n' \
  > "$ZEROCLAW_DATA_DIR/agents/default/SOUL.md"

fn agent_file_present(workspace_dir: &std::path::Path, name: &str) -> bool {
    workspace_dir.join(name).is_file()
}

When it happens

Trigger: Running `zeroclaw doctor` when an enabled agent's workspace directory exists but lacks `SOUL.md` or `AGENTS.md` (checked with `workspace_dir.join(name).is_file()`).

Common situations: Fresh agent created via config without running the init/quickstart that writes persona files; workspace directory moved or recreated; agents migrated to a new `data_dir` without copying persona files.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• agent "{name}" uses invalid model_provider "{provider_ref}":
• low disk space: only {avail_mb} MB available
• agents.{agent_alias}.model_provider is empty; runtime reload
• start_channels requires at least one enabled [agents.<alias>
• model route "{}" uses invalid model_provider "{}": {}

AI-assisted analysis of zeroclaw-labs/zeroclaw@88bb9c8533 (2026-08-23). Data as JSON: /api/errors/c338158bdec75e2d. Report an issue: GitHub.