dependency_prereleases must be disallow, allow…

Error message

dependency_prereleases must be disallow, allow, if-necessary, or explicit

What it means

The mise pipx backend's dependency_prereleases option only accepts four exact string values: "disallow", "allow", "if-necessary", or "explicit". This value is forwarded to uv's prerelease resolution strategy when building dependency-locked installs, so an unrecognized string is rejected at validation time rather than silently mis-resolving. The backend bails to surface the typo immediately.

Solutions

Change dependency_prereleases to exactly one of: disallow, allow, if-necessary, or explicit
If you meant the uv CLI value "if-necessary-or-explicit", use "explicit" or "if-necessary" instead
Remove the dependency_prereleases option if you don't need prerelease control

Example fix

// before (mise.toml)
[tools]
"pipx:ruff" = { version = "latest", dependency_prereleases = "if_necessary" }
// after
[tools]
"pipx:ruff" = { version = "latest", dependency_prereleases = "if-necessary" }

Defensive patterns

Strategy: validation

Validate before calling

const ALLOWED = new Set(["disallow", "allow", "if-necessary", "explicit"]);
if (opts.dependency_prereleases && !ALLOWED.has(opts.dependency_prereleases))
  throw new Error(`dependency_prereleases must be one of: ${[...ALLOWED].join(", ")}`);

Type guard

function isPrereleaseMode(v: unknown): v is "disallow" | "allow" | "if-necessary" | "explicit" {
  return v === "disallow" || v === "allow" || v === "if-necessary" || v === "explicit";
}

Prevention

Copy allowed values verbatim from the docs; use hyphens (if-necessary), not underscores
Schema-validate mise.toml tool options (mise has a JSON schema) before committing

When it happens

Trigger: Setting dependency_prereleases in pipx tool options (e.g. mise.toml [tools]."pipx:ruff" options) to any string outside the four allowed values, such as "if_necessary" (underscore), "always", "true", or "Dis-Allow". The check runs in the option parser called by has_uv_only_options, validate_semantic, and uv_install_args.

Common situations: Typos or wrong casing when writing the option by hand; using Python-style booleans like "true"/"false"; copying uv CLI flag names (--prerelease=if-necessary-or-explicit) that don't match the option's enumerated set; config from an older/newer version with different allowed values.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of jdx/mise@533346cc37 (2026-09-17). Data as JSON: /api/errors/084094f3aabb3626. Report an issue: GitHub.

Appendix: source

Thrown at src/backend/pipx.rs:136

    fn requirement_package_name(requirement: &str) -> Option<&str> {
        let name = requirement
            .trim()
            .split(|c: char| !(c.is_ascii_alphanumeric() || matches!(c, '-' | '_' | '.')))
            .next()
            .unwrap_or_default();
        (!name.is_empty()).then_some(name)
    }

    fn dependency_prereleases(&self) -> Result<Option<&'a str>> {
        let value = match self.values.raw().opts.get("dependency_prereleases") {
            Some(toml::Value::String(value)) => Some(value.as_str()),
            Some(_) => bail!("dependency_prereleases must be a string"),
            None => None,
        };
        if value.is_some_and(|value| {
            !matches!(value, "disallow" | "allow" | "if-necessary" | "explicit")
        }) {
            bail!("dependency_prereleases must be disallow, allow, if-necessary, or explicit");
        }
        Ok(value)
    }

    fn has_uv_only_options(&self) -> Result<bool> {
        Ok(!self.with()?.is_empty()
            || !self.expose()?.is_empty()
            || self.dependency_prereleases()?.is_some())
    }

    fn validate_semantic(&self) -> Result<()> {
        self.with()?;
        self.exposed_package_names()?;
        self.dependency_prereleases()?;
        if self.has_uv_only_options()? && self.uvx_disabled() {
            bail!("with, expose, and dependency_prereleases cannot be combined with uvx = false");
        }
        Ok(())

View on GitHub (pinned to 533346cc37)