mise oci build does not support asdf/vfox plugins in v1 (the

Error message

mise oci build does not support asdf/vfox plugins in v1 (their install scripts can write outside the per-version directory, breaking the one-layer-per-tool invariant). Affected tools: {bad.join}

What it means

mise's `oci build` supports only backends whose installation is confined to a per-version directory, because each tool becomes its own OCI layer. asdf and vfox plugin install scripts can write arbitrary files outside that directory, so build fails fast when any requested tool uses such a backend, listing the affected tools.

Source

Thrown at src/oci/builder.rs:1139

fn reject_unsupported_backends(
    versions: &[(Arc<dyn crate::backend::Backend>, ToolVersion)],
) -> Result<()> {
    // Ask the actual backend instance rather than parsing the short name.
    // `BackendType::guess` only matches literal "asdf" / "vfox" prefixes and
    // misses third-party vfox plugins whose tools use a custom plugin name
    // as the prefix (e.g. `my-plugin:tool`), even though they have the same
    // out-of-tree write behavior we're guarding against.
    let bad: Vec<String> = versions
        .iter()
        .filter_map(|(backend, tv)| match backend.get_type() {
            BackendType::Asdf | BackendType::Vfox | BackendType::VfoxBackend(_) => {
                Some(tv.ba().short.clone())
            }
            _ => None,
        })
        .collect();
    if !bad.is_empty() {
        bail!(
            "mise oci build does not support asdf/vfox plugins in v1 (their install scripts can \
             write outside the per-version directory, breaking the one-layer-per-tool invariant). \
             Affected tools: {}",
            bad.join(", ")
        );
    }
    Ok(())
}

/// Rewrite any occurrence of the host install path in an `exec_env` value to
/// the corresponding in-image path. Handles both exact matches
/// (`JAVA_HOME=<install>`) and colon-separated PATH-like values
/// (`SOMETHING=<install>/foo:<install>/bar`).
fn rebase_path_value(value: &str, host_prefix: &std::path::Path, in_image_prefix: &str) -> String {
    let host: &str = &host_prefix.to_string_lossy();
    if host.is_empty() || !value.contains(host) {
        return value.to_string();
    }

View on GitHub (pinned to afd2eddd3a)

Solutions

Replace asdf/vfox-based tools in the toolset with native backends (core plugins, aqua:, github:, cargo:, npm:, etc.) before building the OCI image.
Check `mise ls --json` (or the tool resolution) to identify which tools use asdf/vfox backends, per the 'Affected tools' list in the message.
Install those tools with a supported backend, e.g. `mise use aqua:owner/repo` or `mise use github:owner/repo`, then rerun `mise oci build`.

Example fix

// before (.mise.toml)
[tools]
"asdf:nodejs" = "20"
// after
[tools]
node = "20"

Defensive patterns

Strategy: validation

Validate before calling

const UNSUPPORTED = ["asdf", "vfox"];
function assertNoPluginBackends(tools) {
  const bad = tools.filter(t => UNSUPPORTED.includes(t.backendShort));
  if (bad.length) throw new Error(`oci build unsupported backends: ${bad.map(t => t.name).join(", ")}`);
}

Try / catch

try {
  buildOciImage(tools);
} catch (e) {
  if (String(e).includes("asdf/vfox plugins")) {
    console.error("swap these tools to native/aqua/github backends first:", e.message);
    process.exit(1);
  }
  throw e;
}

Prevention

Prefer core, aqua:, github:, cargo:, npm: backends over asdf/vfox plugins in images.
Audit `mise ls --json` for asdf/vfox backends before adding oci build to CI.
Pin tool sources in mise.toml so a registry change cannot silently switch a tool to an asdf backend.

When it happens

Trigger: Running `mise oci build` where the resolved toolset includes any tool whose backend short name is asdf or vfox (e.g. an asdf-installed plugin like `asdf:some/plugin`); reject_unsupported_backends collects these and bails before layer building.

Common situations: Migrating an existing toolset that still relies on legacy asdf plugins or vfox plugins to OCI image building; a registry entry resolving to an asdf backend unintentionally.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/bacf88014526ff65. Report an issue: GitHub.