unicity-aos/aos-ce · warning · Finding

Unknown capability field

Error message

Unknown capability field `{key}`.

What it means

During manifest validation, check_capabilities iterates the [capabilities] table and only recognizes documented capability keys. Any key that is not a known capability (and not a boolean-valued known field) produces this warning telling the author the field is ignored. Forge fails closed: unknown capabilities grant nothing, so a typo silently disables the intended capability.

Solutions

1. Run `forge_guide` topic `capabilities` to list valid capability fields and use one of those exact names.
2. Fix typos in the capability key (the warning names the offending key).
3. If migrating from an older capsule, check the forge changelog for renamed capabilities and update the manifest.
4. Remove the unknown key entirely if the capability is not actually needed.

Example fix

# before
[capabilities]
netwok = true
# after
[capabilities]
network = true

# check capability names against forge_guide before validating
forge_guide topic capabilities  # list valid keys, then diff your [capabilities] table

When it happens

Trigger: validate_manifest -> check_capabilities finds a key under [capabilities] that is not in the set of current capability names; typically a typo (e.g. capability = netwok) or a capability renamed in a newer forge version.

Common situations: Copying an example manifest from an outdated blog post or old template; misspelling a capability name; inventing a plausible capability that doesn't exist; upgrading forge where a capability was renamed.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Subscribe ` ` has priority outside the u32 range.
• Subscribe ` ` priority must be an integer.
• Subscribe ` ` has no `handler`.
• Mandatory publish key
• Subscribe `tool.v1.request.describe` is missing — tools…

AI-assisted analysis of unicity-aos/aos-ce@f6f22024fb (2026-09-13). Data as JSON: /api/errors/e8292399a1f136ae. Report an issue: GitHub.

Appendix: source

Thrown at capsules/capsule-forge/src/checks.rs:120

    const BOOL_FIELDS: &[&str] = &["uplink", "allow_persistent", "allow_prompt_injection"];

    for (key, value) in capabilities {
        if LIST_FIELDS.contains(&key.as_str()) {
            if !value.is_array() {
                out.push(Finding::err(
                    format!("Capability `{key}` must be a list."),
                    format!("Use `{key} = [\"scope\"]`, or omit it when unused."),
                ));
            }
        } else if BOOL_FIELDS.contains(&key.as_str()) {
            if !value.is_bool() {
                out.push(Finding::err(
                    format!("Capability `{key}` must be a boolean."),
                    format!("Use `{key} = true` or omit it (the default is false)."),
                ));
            }
        } else {
            out.push(Finding::warn(
                format!("Unknown capability field `{key}`."),
                "Use only the current fields documented by `forge_guide` topic `capabilities`.",
            ));
        }
    }

    if capabilities
        .get("kv")
        .and_then(Toml::as_array)
        .is_some_and(|values| !values.is_empty())
    {
        out.push(Finding::info(
            "The `kv` capability field is reserved; ordinary capsule KV does not require it.",
            "Omit `kv` unless the pinned runtime contract specifically requires it.",
        ));
    }
}

View on GitHub (pinned to f6f22024fb)