jdx/mise · error

repo path `{path_raw}` cannot start with `~`; use `~/` for a

Error message

repo path `{path_raw}` cannot start with `~`; use `~/` for a home-relative path

What it means

RepoRequest::from_toml validates the `[repos]` path string from a TOML configuration. A path that begins with `~` but is not exactly the home-relative form `~/...` (e.g. `~alice/repo`, `~config`) is rejected, because bare `~` prefixes are ambiguous (another user's home vs a literal directory name) and are not expanded by `replace_path`. Only `~/` is accepted as a home-relative shorthand.

Source

Thrown at src/system/repos.rs:81

}

#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct RepoStatus {
    pub request: RepoRequest,
    pub origin: Option<String>,
    pub current_ref: Option<String>,
    pub current_sha: Option<String>,
    pub state: RepoState,
}

impl RepoRequest {
    pub(crate) fn from_toml(
        path_raw: String,
        config: RepoTomlConfig,
        project_root: Option<&Path>,
    ) -> Result<Self> {
        if path_raw.starts_with('~') && !path_raw.starts_with("~/") {
            bail!(
                "repo path `{path_raw}` cannot start with `~`; use `~/` for a home-relative path"
            );
        }
        let path = file::replace_path(&path_raw);
        let path = if path.is_absolute() {
            path
        } else {
            let Some(root) = project_root else {
                bail!(
                    "relative repo paths are only allowed in a project config; use an absolute path or a `~/` path"
                );
            };
            if path.components().any(|component| {
                matches!(
                    component,
                    Component::ParentDir | Component::RootDir | Component::Prefix(_)
                )
            }) {

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Use the home-relative form: change `~user/repo` to `~/repo` (your own home).
2. Use the full absolute path (`/home/otheruser/repo`) if you truly need another user's home directory.
3. If `~` is meant as a literal directory name, prefix with `./` (project-relative) or use an absolute path.
4. Escape nothing — the tilde shorthand is exactly `~/`; anything else must be absolute or relative.

Example fix

// before (mise.toml)
[[repos]]
path = "~shared/tools-repo"
// after
[[repos]]
path = "~/tools-repo"   # or an absolute path

function validateRepoPath(p) {
  if (p.startsWith('~') && !p.startsWith('~/')) {
    throw new Error(`repo path '${p}' must use '~/` for home-relative paths`);
  }
}

When it happens

Trigger: Writing a repo entry in mise.toml with a path like `~user/repos/foo` or `~foo` — any value where the first character is `~` but the second is not `/`.

Common situations: Copy-pasting a path like `~otheruser/config` from shell history expecting tilde-user expansion; typos such as `~config` missing the slash; misunderstanding that only `~/` shorthand is supported.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• failed to parse registry option {k} as a TOML value: {e}
• aqua var `{}` must be a string, got {}
• config set requires a TOML config file, but {} is not TOML
• Type not found
• collection updates require scalar or array values

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