jdx/mise · error

Unknown shim mode

Error message

Unknown shim mode

What it means

Returned by run_all_rebuilds in src/runtime_symlinks.rs:52. mise maintains convenience symlinks (e.g. 'latest' -> <version>) inside each backend's install directories, including shared/system install dirs; rebuild_for_backends runs one rebuild per (backend, installs_dir) and collects every failure instead of stopping at the first. If any rebuild errors (each wrapped as 'failed to rebuild runtime symlinks for <backend> in <dir>'), mise returns one aggregate error listing the count and each per-directory cause with full context chains.

Source

Thrown at src/shims.rs:576

            })
        }
        "hardlink" => fs::hard_link(mise_bin, symlink_path).wrap_err_with(|| {
            eyre!(
                "Failed to create hardlink from {} to {}",
                display_path(mise_bin),
                display_path(symlink_path)
            )
        }),
        "symlink" => {
            std::os::windows::fs::symlink_file(mise_bin, symlink_path).wrap_err_with(|| {
                eyre!(
                    "Failed to create symlink from {} to {}",
                    display_path(mise_bin),
                    display_path(symlink_path)
                )
            })
        }
        _ => panic!("Unknown shim mode"),
    }
}

#[cfg(unix)]
fn add_shim(mise_bin: &Path, symlink_path: &Path, _shim: &str) -> Result<()> {
    file::make_symlink(mise_bin, symlink_path).wrap_err_with(|| {
        eyre!(
            "Failed to create symlink from {} to {}",
            display_path(mise_bin),
            display_path(symlink_path)
        )
    })?;
    Ok(())
}

pub struct ShimDiffs {
    pub missing: BTreeSet<String>,
    pub extra: BTreeSet<String>,

View on GitHub (pinned to 9dcfcaa0dc)

Solutions

1. Read each line of the aggregated message: it names the backend and installs dir, plus the underlying IO error — fix the number-one cause first
2. Fix ownership/permissions on the affected installs dir: `sudo chown -R "$(id -un)" <dir>` (or chmod u+w), then re-run the mise command
3. If a stale real directory sits at a symlink slot, remove it manually (`rm -rf <installs>/<tool>/<name>`) and rerun so the symlink can be created
4. Ensure only one mise instance runs at a time per data dir (no parallel CI steps sharing MISE_DATA_DIR), then retry
5. If the dir is intentionally read-only (system install), exclude it from shared install dirs (unset MISE_SHARED_INSTALL_DIRS / shared config) so repair skips it

Example fix

# before: shared installs dir created by root, repair fails
# error: 1 runtime symlink repair(s) failed:
# failed to rebuild runtime symlinks for node in /opt/mise-shared: Permission denied (os error 13)

# after: take ownership, then re-run
sudo chown -R "$(id -un):$(id -gn)" /opt/mise-shared
mise install   # symlink repair now succeeds

# verify every installs dir mise will repair is writable before running mise
for d in "${MISE_DATA_DIR:-$HOME/.local/share/mise}/installs"/* ${MISE_SHARED_INSTALL_DIRS:-}; do
  [ -d "$d" ] || continue
  [ -w "$d" ] || echo "NOT WRITABLE: $d -> chown or exclude it"
done

Catch the aggregate eyre error, split on '\n' to get per-directory causes, and handle each independently: permission failures -> prompt/escalate for that dir only; transient locks -> single retry after the other mise process exits. Do not blanket-retry the whole operation.

When it happens

Trigger: Any mise operation that triggers runtime symlink repair (toolset activation, install, use, prune) where at least one install dir cannot be updated: no write permission on a shared/system installs dir (see install_dirs_for, which includes env shared dirs), an existing symlink that cannot be resolved or removed, a stale real directory at a symlink slot that remove_all fails to delete, a file locked by another process (Windows), or a disk/IO error.

Common situations: MISE_* shared install directories owned by root or another user (created via sudo earlier); system-level installs (/usr/local/...) included in shared_install_dirs on locked-down hosts; two mise processes repairing the same dir concurrently; antivirus/EDR briefly holding handles on Windows; NFS-mounted home dirs with broken symlink semantics.

Related errors

• {} is still not writable after bootstrap
• {err}. Creating directory symlinks on Windows may require ad
• Infinitive loop detected, all tasks are finished but the gra
• bootstrap plan contains resources with unknown state
• {}: does not look like an OCI image layout (missing index.js

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