abiosoft/colima · error

relative paths not supported for mount '%s'

Error message

relative paths not supported for mount '%s'

What it means

CleanPath (util/util.go:154-171) normalizes a mount location for Lima mounts: it skips empty strings, expands environment variables (os.ExpandEnv), expands a leading ~ to the home dir, cleans the path, then rejects anything that is not absolute with 'relative paths not supported for mount'. Lima bind mounts operate on host paths the VM must resolve, so colima requires an unambiguous absolute location before VM start.

Source

Thrown at util/util.go:169

	return split
}

// CleanPath returns the absolute path to the mount location.
// If location is an empty string, nothing is done.
func CleanPath(location string) (string, error) {
	if location == "" {
		return "", nil
	}

	str := os.ExpandEnv(location)

	if strings.HasPrefix(str, "~") {
		str = strings.Replace(str, "~", HomeDir(), 1)
	}

	str = filepath.Clean(str)
	if !filepath.IsAbs(str) {
		return "", fmt.Errorf("relative paths not supported for mount '%s'", location)
	}

	return strings.TrimSuffix(str, "/") + "/", nil
}

View on GitHub (pinned to c3a5f9184d)

Solutions

1. Use an absolute path or a leading ~: `--mount location=~/src,target=/src`
2. Ensure every $VAR referenced in a mount location is actually set in colima's environment (unset vars expand to empty, making the path relative)
3. For repo-local dirs, pass $(pwd): `--mount location=$(pwd)/src,target=/src`
4. Keep mounts in ~/.colima/_lima/<profile> overrides consistent and absolute

Example fix

# before
colima start --mount type=9p,location=./www,target=/www
# Error: relative paths not supported for mount './www'

# after
colima start --mount type=9p,location=~/projects/www,target=/www

// validate a mount location exactly like CleanPath does, before start
func validMountLocation(loc string) error {
    s := filepath.Clean(os.ExpandEnv(loc))
    if strings.HasPrefix(s, "~") { s = filepath.Clean(HomeDir() + s[1:]) }
    if !filepath.IsAbs(s) { return fmt.Errorf("mount %q must be absolute", loc) }
    return nil
}

func isRelativeMountError(err error) bool {
    return err != nil && strings.Contains(err.Error(), "relative paths not supported for mount")
}

if p, err := util.CleanPath(location); err != nil {
    if isRelativeMountError(err) {
        // user-fixable: tell them to prefix with ~ or $(pwd), then exit
        return fmt.Errorf("fix mount path and retry: %w", err)
    }
    return err
}

When it happens

Trigger: `colima start --mount type=9p,location=./src,target=/src` (cwd-relative), `--mount location=www:target=/www`, or mounts in the colima YAML/CLI flags where an expanded $VAR ends up relative because the variable is unset (expands to empty).

Common situations: Docker users assuming `docker run -v src:/dst`-style relative bind paths; unset environment variables inside mount strings; tilde placed mid-path where it isn't expanded; config files written on one machine with absolute paths valid only there.

Related errors

• mount path with spaces is not supported by the underlying Li
• overlapping mounts not supported: %w
• invalid mountType: '%s'
• error sanitising mount path for inotify: %w
• invalid directory: %w

AI-assisted analysis of abiosoft/colima@c3a5f9184d (2026-08-15). Data as JSON: /api/errors/4f5a1cf8329120b0. Report an issue: GitHub.