[bootstrap.macos.dock].apps: expected a path relative to…

Error message

[bootstrap.macos.dock].apps: expected a path relative to home: {value}

What it means

Thrown by dock::paths while validating [bootstrap.macos.dock].apps entries. Values written as "~/..." must be relative to the home directory; if the portion after "~/" still has a root component (e.g. "~//abs" or "~/C:/x" style input), joining it to HOME would silently discard HOME, so the value is rejected.

Solutions

Write the value as a plain absolute path (e.g. "/Applications/Foo.app") instead of "~/..."
Fix the path so everything after "~/" is genuinely relative (no leading slash or drive letter)
Check templates/variables that interpolate into the apps array for accidental absolute expansions

Example fix

// before
apps = ["~//Applications/Safari.app"]
// after
apps = ["~/Applications/Safari.app"]  // or "/Applications/Safari.app"

Defensive patterns

Strategy: validation

Validate before calling

fn validate_dock_app(value: &str) -> Result<(), String> {
    if let Some(rest) = value.strip_prefix("~/") {
        if Path::new(rest).has_root() {
            return Err(format!("{value} is not relative to home"));
        }
    }
    Ok(())
}

Type guard

fn is_home_relative_tilde(value: &str) -> bool {
    value.strip_prefix("~/").map_or(false, |r| !Path::new(r).has_root())
}

Prevention

Use either plain absolute paths or clean "~/relative" forms, never mixed
Watch for double slashes and expanded variables after "~/"
Lint dock.apps entries for path shape before applying

When it happens

Trigger: A dock.apps entry of the form "~/<rooted-path>", e.g. "~/ /Applications/Foo.app" or "~/\\\\host\\share\\Foo.app", where strip_prefix("~/") leaves an absolute path.

Common situations: Double slashes or stray spaces after the tilde; Windows-style absolute paths pasted after ~; mis-templated paths where a variable expanded to an absolute path following "~/".

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at src/system/defaults/dock.rs:18

//! Application layout semantics for the friendly Dock setting. Raw defaults remain exact.
use std::path::{Component, Path, PathBuf};

use super::DefaultsValue;
use crate::result::Result;

pub(super) fn paths(value: &DefaultsValue) -> Result<Vec<PathBuf>> {
    let DefaultsValue::Array(values) = value else {
        eyre::bail!("[bootstrap.macos.dock].apps: expected an array of application paths");
    };
    let mut paths = Vec::new();
    let mut seen = std::collections::HashSet::new();
    for value in values {
        let DefaultsValue::Str(value) = value else {
            eyre::bail!("[bootstrap.macos.dock].apps: expected an array of application paths");
        };
        let path = if let Some(rest) = value.strip_prefix("~/") {
            eyre::ensure!(
                !Path::new(rest).has_root(),
                "[bootstrap.macos.dock].apps: expected a path relative to home: {value}"
            );
            crate::env::HOME.join(rest)
        } else {
            PathBuf::from(value)
        };
        eyre::ensure!(
            path.is_absolute()
                && path
                    .extension()
                    .is_some_and(|ext| ext.eq_ignore_ascii_case("app"))
                && !path.components().any(|c| matches!(c, Component::ParentDir))
                && !value.contains('\0'),
            "[bootstrap.macos.dock].apps: expected an absolute or ~/ application path: {value}"
        );
        let path: PathBuf = path.components().collect();
        eyre::ensure!(

View on GitHub (pinned to 533346cc37)