zeroclaw-labs/zeroclaw · error

at least one path must be configured

Error message

at least one path must be configured

What it means

The filesystem SOP listener watches a list of directory paths and lifts create/modify/delete/rename events into the SOP engine. `FilesystemConfig::validate` requires at least one path because a watcher with an empty `paths` list (the serde default) would register nothing and the enabled channel would be a silent no-op.

Source

Thrown at crates/zeroclaw-config/src/schema.rs:16422

            settle_ms: default_filesystem_settle_ms(),
            read_content: false,
            follow_symlinks: false,
            max_content_bytes: default_filesystem_max_content_bytes(),
            allow_broad_roots: false,
            excluded_tools: Vec::new(),
        }
    }
}

const FILESYSTEM_BROAD_ROOTS: [&str; 8] = [
    "/", "/home", "/etc", "/var", "/proc", "/sys", "/dev", "/tmp",
];

impl FilesystemConfig {
    /// Validate the filesystem listener configuration.
    pub fn validate(&self) -> anyhow::Result<()> {
        if self.paths.is_empty() {
            anyhow::bail!("at least one path must be configured");
        }
        for path in &self.paths {
            let trimmed = path.trim_end_matches('/');
            let normalized = if trimmed.is_empty() { "/" } else { trimmed };
            if !self.allow_broad_roots && FILESYSTEM_BROAD_ROOTS.contains(&normalized) {
                anyhow::bail!(
                    "path '{path}' is a broad system root; set allow_broad_roots = true to watch it"
                );
            }
        }
        for kind in &self.events {
            if !matches!(
                kind.as_str(),
                "created" | "modified" | "deleted" | "renamed"
            ) {
                anyhow::bail!(
                    "event '{kind}' is invalid; expected created, modified, deleted, or renamed"
                );

View on GitHub (pinned to 88bb9c8533)

Solutions

1. Add at least one absolute directory path, e.g. `paths = ["/var/lib/zeroclaw/inbox"]`.
2. Prefer the narrowest directory that covers the events you need.
3. If the path is a broad system root, see the separate broad-root validation before enabling `allow_broad_roots`.

Example fix

# before
[channels.filesystem.watch]
enabled = true
# no paths

# after
[channels.filesystem.watch]
enabled = true
paths = ["/var/lib/zeroclaw/inbox"]

anyhow::ensure!(
    !fs_cfg.paths.is_empty(),
    "channels.fileswatch alias needs at least one path"
);

When it happens

Trigger: `[channels.filesystem.<alias>]` with `enabled = true` but no `paths` key; `paths = []` written explicitly; paths moved to another key by mistake during config refactors.

Common situations: Enabling the channel from a template before choosing watch directories; YAML/TOML indentation mistakes that leave `paths` under the wrong table so it parses as unset.

Related errors

• at least one topic must be configured
• path '{path}' is a broad system root; set allow_broad_roots
• event '{kind}' is invalid; expected created, modified, delet
• at least one routing key must be configured
• cloud_ops.default_cloud must not be empty when cloud_ops is

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