invalid Nix flake reference

Error message

invalid Nix flake reference '{source}'; use a registry name, URL, or path:/absolute/path

What it means

When a package reference contains `#`, the part before it is treated as an explicit flake source and must be a registry flake name, a flake URL (github:/git+https: etc.), or an absolute `path:/...` reference. The parser rejects empty sources, sources starting with `-`, `.`, or `/`, and relative `path:` refs, because such strings are not valid flake refs (and `-`-prefixed input could be misread as a CLI flag).

Solutions

Use an absolute path reference: `path:/absolute/path/to/flake#attribute`.
Use a registry flake name (`nixpkgs#ripgrep`) or a full flake URL (`github:owner/repo#attr`).
Remove stray leading `-`, `.`, `/`, or `#` characters from the source part.
Pin local flakes by absolute path plus revision in the flake URL if reproducibility is needed.

Example fix

# before
packages = ["./local-flake#hello"]

# after
packages = ["path:/home/me/local-flake#hello"]

Defensive patterns

Strategy: validation

Validate before calling

fn looks_like_flake_source(src: &str) -> bool {
    !src.is_empty()
        && !src.starts_with(['-', '.', '/'])
        && (!src.starts_with("path:") || src.strip_prefix("path:").unwrap().starts_with('/'))
}

Prevention

Use path:/absolute/... for local flakes
Use registry names or full URLs for sources
Never start a source with -, ., or /
Test references with `nix flake metadata <ref>` first

When it happens

Trigger: `Installable::parse` sees a name with `#` whose prefix is empty (`#hello`), flag-like (`--expr#hello`), a plain relative path (`./local#hello`, `/tmp/x#hello`), or `path:relative#hello`.

Common situations: Users writing local-path packages as `./my-flake#pkg` instead of `path:/abs/my-flake#pkg`; typos like a leading `#` from copy-paste; treating mise package entries as raw nix expressions.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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

Appendix: source

Thrown at src/system/packages/nix.rs:38

    pub explicit: bool,
}

impl<'a> Installable<'a> {
    pub(crate) fn parse(name: &'a str) -> Result<Self> {
        if name.chars().any(char::is_control) {
            bail!("Nix package references must not contain control characters");
        }
        let (source, attribute, explicit) = match name.split_once('#') {
            Some((source, attribute)) => {
                if source.is_empty()
                    || source.starts_with('-')
                    || source.starts_with('.')
                    || source.starts_with('/')
                    || source
                        .strip_prefix("path:")
                        .is_some_and(|p| !p.starts_with('/'))
                {
                    bail!(
                        "invalid Nix flake reference '{source}'; use a registry name, URL, or path:/absolute/path"
                    );
                }
                (source, attribute, true)
            }
            None => ("nixpkgs", name, false),
        };
        if !valid_attribute(attribute) {
            bail!(
                "invalid Nix package attribute '{attribute}'; use a dotted attribute path (e.g. ripgrep or python3Packages.pip), or '<flake>#<attribute>'; pin versions in the flake reference, not with @version"
            );
        }
        Ok(Self {
            source,
            attribute,
            explicit,
        })
    }

View on GitHub (pinned to 533346cc37)