What causes "invalid destination path: %v" in hashicorp/nomad?

Set file to a simple relative path such as "payload.txt" — the payload lands under task/local/.

invalid destination path: %v

Error message

invalid destination path: %v

What it means

DispatchPayloadConfig.Validate checks that the task-relative destination File path does not escape the allocation directory, using escapingfs.PathEscapesAllocViaRelative("task/local/", d.File). If the path check itself errors, this wrapping error is returned; if the path escapes, a separate escape error is returned instead.

Source

Thrown at nomad/structs/structs.go:6149

type DispatchPayloadConfig struct {
	// File specifies a relative path to where the input data should be written
	File string
}

func (d *DispatchPayloadConfig) Copy() *DispatchPayloadConfig {
	if d == nil {
		return nil
	}
	nd := new(DispatchPayloadConfig)
	*nd = *d
	return nd
}

func (d *DispatchPayloadConfig) Validate() error {
	// Verify the destination doesn't escape
	escaped, err := escapingfs.PathEscapesAllocViaRelative("task/local/", d.File)
	if err != nil {
		return fmt.Errorf("invalid destination path: %v", err)
	} else if escaped {
		return fmt.Errorf("destination escapes allocation directory")
	}

	return nil
}

const (
	TaskLifecycleHookPrestart  = "prestart"
	TaskLifecycleHookPoststart = "poststart"
	TaskLifecycleHookPoststop  = "poststop"
)

type TaskLifecycleConfig struct {
	Hook    string
	Sidecar bool
}

View on GitHub (pinned to 482b49bf1a)

Solutions

Set file to a simple relative path such as "payload.txt" — the payload lands under task/local/.
Remove any leading "/", drive letters, or .. segments from the file value.
Verify the value with PathEscapesAllocViaRelative (or filepath.Clean + prefix check) before submitting.
Run `nomad job validate` to confirm the corrected dispatch_payload block.

Example fix

// before
dispatch_payload {
  file = "/tmp/payload.json"
}
// after
dispatch_payload {
  file = "payload.json"
}

Defensive patterns

Strategy: validation

Validate before calling

func safeDispatchFile(dest string) bool {
    if dest == "" {
        return false
    }
    clean := filepath.Clean(dest)
    return !filepath.IsAbs(clean) && !strings.HasPrefix(clean, "..")
}
// call before submitting: if !safeDispatchFile(dp.File) { ... }

Try / catch

if err := dp.Validate(); err != nil {
    if strings.Contains(err.Error(), "invalid destination path") || strings.Contains(err.Error(), "escapes") {
        // replace with a plain relative filename
    }
}

Prevention

Use simple relative filenames ("payload.txt") for dispatch_payload.file.
Never use absolute paths or ".." segments.
Normalize paths with filepath.Clean and reject anything containing "..".
Use forward slashes; avoid OS-specific separators in job specs.

When it happens

Trigger: Submitting a dispatch/parameterized job whose dispatch_payload block sets file to a path that cannot be safely evaluated relative to task/local/ — e.g. empty, containing invalid separators, or tripping the relative-path checker.

Common situations: Setting file to absolute paths like "/etc/passwd" or paths with .. segments; OS-specific path confusion (backslashes on Linux); path strings built programmatically with wrong joins.

Related errors

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