What causes "hook JSON alias validation failed: {e}" in xai-org/grok-build?

Read the inner `{e}` to identify which alias or file failed and why.

hook JSON alias validation failed: {e}

Error message

hook JSON alias validation failed: {e}

What it means

`capability_set_from_profile` calls `validated_hook_json_files_for_sources` to resolve and validate hook JSON aliases listed in the profile's write_deny entries (unix only); this error wraps any failure from that validation. It means one of the write_deny entries names a hook JSON alias that cannot be validated or resolved to a concrete file, so the capability set cannot be built.

Source

Thrown at crates/codegen/xai-grok-sandbox/src/profiles.rs:306

        for dev in DEVICE_DIRS {
            let p = Path::new(dev);
            if p.exists() && p.is_dir() {
                caps = caps.allow_path(dev, AccessMode::ReadWrite)?;
            }
        }

        // Direct global-hook write-deny (macOS Seatbelt; Linux via bwrap).
        if !profile.write_deny.is_empty() {
            let mut pairs: Vec<(PathBuf, bool)> = profile
                .write_deny
                .iter()
                .map(|s| (s.path.clone(), s.is_dir()))
                .collect();
            #[cfg(unix)]
            {
                let files =
                    xai_grok_config::validated_hook_json_files_for_sources(&profile.write_deny)
                        .map_err(|e| anyhow::anyhow!("hook JSON alias validation failed: {e}"))?;
                for f in files {
                    if !pairs.iter().any(|(p, _)| p == &f) {
                        pairs.push((f, false));
                    }
                }
            }
            apply_write_deny_paths_to_capability_set(&mut caps, &pairs, &profile.read_write)?;
        }

        // Kernel deny (read+write): macOS Seatbelt rules; Linux via bwrap bind-over.
        // Key on an empty deny set, not profile type, so nothing unintentional is enforced.
        //
        // Split exact paths from globs: exact paths keep the literal/subpath flow;
        // globs become anchored Seatbelt regexes on macOS (a no-op here on Linux,
        // where they are expanded and bound over at bwrap re-exec).
        let (exact_deny, glob_deny) = partition_deny_entries(&profile.deny);
        let all_denied = effective_deny_paths(workspace, &exact_deny);
        if !all_denied.is_empty() {

View on GitHub (pinned to bc7f02eddd)

Solutions

Read the inner `{e}` to identify which alias or file failed and why.
Check the write_deny list in your profile (sandbox.toml) for typos in alias names.
Verify the referenced hook JSON file exists and passes schema validation.
Update the alias name if the library renamed built-ins in a newer version.
Remove the invalid alias from write_deny if it is no longer needed.

Example fix

// before (sandbox.toml)
write_deny = ["secrets-json", "credential-deny"] // 'credential-deny' no longer exists
// after
write_deny = ["secrets-json"]

Defensive patterns

Strategy: validation

Validate before calling

fn validate_profile_aliases(profile: &SandboxProfile) -> Result<(), String> {
    xai_grok_config::validated_hook_json_files_for_sources(&profile.write_deny)
        .map(|_| ())
        .map_err(|e| format!("profile write_deny aliases invalid: {e}"))
}
// call after loading the profile, before building the capability set

Try / catch

match capability_set_from_profile(profile, workspace) {
    Ok(cs) => cs,
    Err(e) if e.to_string().contains("hook JSON alias validation failed") => {
        eprintln!("Bad alias in write_deny: {e:#}\nCheck sandbox.toml aliases against the built-in registry.");
        std::process::exit(2);
    }
    Err(e) => return Err(e),
}

Prevention

Keep write_deny alias names in sync with the library's built-in registry when upgrading.
Avoid hand-typing alias names; copy them from the documented list.
Validate custom hook JSON against the expected schema before referencing it.
Add a startup check that resolves every alias and fails fast with a clear message.

When it happens

Trigger: A write_deny entry references a hook JSON alias that does not exist in the config registry; the referenced JSON file fails schema/content validation; a typo in the alias name in the profile definition.

Common situations: Renamed or removed built-in alias after a version upgrade while an old sandbox.toml still references it; custom hook JSON with malformed content; case-sensitivity mistakes in alias names on unix filesystems.

Related errors

AI-assisted analysis of xai-org/grok-build@bc7f02eddd (2026-08-31). Data as JSON: /api/errors/f7e919604f56729b. Report an issue: GitHub.