What causes "`ref` must not be empty" in jdx/mise?

Delete the `ref` key entirely to track the default branch

`ref` must not be empty

Error message

`ref` must not be empty

What it means

`ref` is optional in a repos entry, but when present it is trimmed and may not be empty. An empty ref would be passed to `git clone --branch <ref>` / `git checkout <ref>` and fail with an obscure git error, so from_toml rejects it at config-parse time.

Source

Thrown at src/system/repos.rs:134

            for component in path.components() {
                if let Component::Normal(segment) = component {
                    resolved.push(segment);
                }
            }
            resolved
        };
        let Some(url) = config.url.map(|s| s.trim().to_string()) else {
            bail!("must set `url`");
        };
        if url.is_empty() {
            bail!("must set a non-empty `url`");
        }
        if url.starts_with('-') {
            bail!("`url` must not start with `-`");
        }
        let git_ref = config.git_ref.map(|s| s.trim().to_string());
        let git_ref = match git_ref {
            Some(git_ref) if git_ref.is_empty() => bail!("`ref` must not be empty"),
            Some(git_ref) if git_ref.starts_with('-') => bail!("`ref` must not start with `-`"),
            other => other,
        };
        Ok(Self {
            path_raw,
            path,
            url,
            git_ref,
        })
    }
}

impl std::fmt::Display for RepoRequest {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", file::display_path(&self.path))
    }
}

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

Delete the `ref` key entirely to track the default branch
Set a real branch name, tag, `refs/...` ref, or commit SHA

Example fix

# before
"~/src/x" = { url = "https://github.com/owner/repo.git", ref = "" }

# after
"~/src/x" = { url = "https://github.com/owner/repo.git" }

Defensive patterns

Strategy: validation

Validate before calling

fn repo_ref_is_usable(cfg: &RepoTomlConfig) -> bool {
    cfg.git_ref.as_deref().is_none_or(|r| !r.trim().is_empty())
}

Type guard

fn repo_ref_valid_or_absent(cfg: &RepoTomlConfig) -> bool {
    cfg.git_ref.as_deref().map_or(true, |r| !r.trim().is_empty())
}

Prevention

Emit no `ref` key rather than an empty one when templating config
Remember `ref` is optional — the default branch is tracked without it

When it happens

Trigger: `ref = ""` or `ref = " "` in an `[bootstrap.repos]` entry.

Common situations: Templating that leaves ref blank when a variable is unset; config generators emitting an empty ref key instead of omitting it.

Related errors

AI-assisted analysis of jdx/mise@9dcfcaa0dc (2026-08-17). Data as JSON: /api/errors/015159690dd6d359. Report an issue: GitHub.