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

Set `ref` to a real branch, tag, or commit SHA (e.g. `ref = "main"`)

`ref` must not be empty

Error message

`ref` must not be empty

What it means

The optional `ref` key, when present, is trimmed and must not be empty. An empty ref would produce a malformed `git checkout ""` / fetch spec, so from_toml rejects it. Omitting `ref` entirely is fine; only an explicit empty value fails.

Solutions

Set `ref` to a real branch, tag, or commit SHA (e.g. `ref = "main"`)
Remove the `ref` key entirely to use the remote's default branch
Fix the templating/variable so the ref value resolves non-empty

Example fix

// before
"~/src/dotfiles" = { url = "https://github.com/jdx/dotfiles.git", ref = "" }
// after
"~/src/dotfiles" = { url = "https://github.com/jdx/dotfiles.git", ref = "main" }

Defensive patterns

Strategy: validation

Validate before calling

function validateRef(entry) {
  if ('ref' in entry && entry.ref.trim() === '') {
    throw new Error('ref, when set, must be a non-empty branch/tag/SHA');
  }
}

Type guard

function hasValidRef(entry) {
  return !('ref' in entry) || (typeof entry.ref === 'string' && entry.ref.trim().length > 0);
}

Prevention

Omit `ref` instead of setting it to an empty string
When templating refs, validate the rendered value resolves to a real branch/tag
Keep default-branch checkouts ref-less

When it happens

Trigger: Writing `ref = ""` or `ref = " "` in a `[bootstrap.repos]` entry while also setting a url.

Common situations: Env/templated ref values that expanded to empty; clearing a branch name without removing the key; placeholder left in generated config.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: 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 533346cc37)