hashicorp/nomad · error

failed to determine relative path base=%q target=%q: %v

Error message

failed to determine relative path base=%q target=%q: %v

What it means

getPathInTaskDir computes the located binary's path relative to the task dir so it can be re-rooted inside the container. If filepath.Rel cannot produce a relative path (e.g. the host path is not under taskDir, or taskDir/hostPath are malformed), this error is thrown, wrapping the Rel error.

Source

Thrown at drivers/shared/executor/executor_linux_cgo.go:1054

	return "", "", fmt.Errorf("file %s not found under path", bin)
}

// getPathInTaskDir searches for the binary in the task directory and nested
// search directory. It returns the absolute path rooted inside the container
// and the absolute path on the host.
func getPathInTaskDir(taskDir, searchDir, bin string) (string, string, error) {

	hostPath := filepath.Join(searchDir, bin)
	err := filepathIsRegular(hostPath)
	if err != nil {
		return "", "", err
	}

	// Find the path relative to the task directory
	rel, err := filepath.Rel(taskDir, hostPath)
	if rel == "" || err != nil {
		return "", "", fmt.Errorf(
			"failed to determine relative path base=%q target=%q: %v",
			taskDir, hostPath, err)
	}

	// Turn relative-to-taskdir path into re-rooted absolute path to avoid
	// libcontainer trying to resolve the binary using $PATH.
	// Do *not* use filepath.Join as it will translate ".."s returned by
	// filepath.Rel. Prepending "/" will cause the path to be rooted in the
	// chroot which is the desired behavior.
	return filepath.Clean("/" + rel), hostPath, nil
}

// getPathInMount for the binary in the mount's host path, constructing the path
// considering that the bin path is rooted in the mount's task path and not its
// host path. It returns the absolute path rooted inside the container and the
// absolute path on the host.
func getPathInMount(mountHostPath, mountTaskPath, bin string) (string, string, error) {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Ensure command.TaskDir is an absolute, clean path before calling Launch
2. Verify the binary's host path is actually beneath the task dir (no unexpected symlinks escaping it)
3. Check custom driver/plugin code that constructs taskDir/hostPath for consistency
4. Update Nomad client if a known path-resolution bug was fixed in a later release

Example fix

// before
taskDir := "alloc/1234/app"            // relative
taskPath, hostPath, err := lookup(taskDir, ...)
// after
taskDir, _ := filepath.Abs("alloc/1234/app")
taskDir = filepath.Clean(taskDir)

taskDir := filepath.Clean(task.TaskDir)
if !filepath.IsAbs(taskDir) {
    return fmt.Errorf("taskDir must be absolute, got %q", taskDir)
}

if err != nil && strings.Contains(err.Error(), "failed to determine relative path") {
    // log base/target from error text; fix driver's taskDir construction
    return fmt.Errorf("taskdir/hostpath mismatch: %w", err)
}

When it happens

Trigger: getPathInTaskDir found the binary (hostPath valid) but filepath.Rel(taskDir, hostPath) returned an error or empty string — typically when hostPath is absolute on a different root than taskDir or taskDir is empty/not absolute.

Common situations: Driver or plugin supplying a non-clean or relative TaskDir; custom drivers extending executor with mismatched task dir and mount paths; symlinks resolving outside the task dir causing path mismatch; Nomad version/config producing empty TaskDir in a custom invocation.

Related errors

• file %s not found under path %s
• file %s not found under path
• path was not relative to the mount task path
• ErrCgroupMustBeSet
• user name must contain domain

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/cc87cb0a206fc081. Report an issue: GitHub.