hashicorp/nomad · warning

failed to resolve requested path: %w

Error message

failed to resolve requested path: %w

What it means

After resolving the alloc dir, sanitizePath() joins the requested path and calls filepath.Abs. If computing the absolute path fails, this wrapped error is returned from all path-consuming APIs (List, Stat, ReadAt, etc.).

Source

Thrown at client/allocdir/alloc_dir.go:423

		}
	}
	return files, err
}

// sanitizePath checks that the path does not escape the alloc directory,
// does not read into the secrets or private directories and returns an absolute
// path of the provided path.
func (a *AllocDir) sanitizePath(path string) (string, error) {
	// In some non linux systmes, directories like /var and /tmp resolve to
	// /private/var and /private/tmp.
	resolvedAllocDir, err := filepath.EvalSymlinks(a.AllocDir)
	if err != nil {
		return "", fmt.Errorf("failed to resolve alloc directory: %w", err)
	}

	requestedPath, err := filepath.Abs(filepath.Join(resolvedAllocDir, path))
	if err != nil {
		return "", fmt.Errorf("failed to resolve requested path: %w", err)
	}

	if err := escapingfs.ChildEscapesParentDir(resolvedAllocDir, requestedPath); err != nil {
		return "", fmt.Errorf("path escapes the alloc directory")
	}

	a.mu.RLock()
	defer a.mu.RUnlock()

	// Check it does not access the secrets or private directories
	for _, taskDir := range a.TaskDirs {
		rps := strings.ReplaceAll(requestedPath, "/Secrets", "/secrets")
		if err := escapingfs.ChildEscapesParentDir(taskDir.SecretsDir, rps); err == nil {
			return "", fmt.Errorf("Reading secret file prohibited: %s", path)
		}

		rpp := strings.ReplaceAll(requestedPath, "/Private", "/private")
		if err := escapingfs.ChildEscapesParentDir(taskDir.PrivateDir, rpp); err == nil {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Shorten the requested path or reduce alloc dir nesting depth
2. Remove invalid characters from the requested path for the target OS
3. Retry once the underlying cause (path length/charset) is corrected

Example fix

// before
allocDir.ReadAt("task/" + strings.Repeat("d/", 200) + "f", 0)
// after
rel := "task/short-name"
allocDir.ReadAt(rel, 0)

if len(path) > 4096 {
    return fmt.Errorf("requested path too long: %d", len(path))
}

f, err := allocDir.ReadAt(path, 0)
if err != nil && strings.Contains(err.Error(), "failed to resolve requested path") {
    return fmt.Errorf("unusable path (too long/invalid for OS?): %q", path)
}

When it happens

Trigger: Calling any file API with a path such that filepath.Abs(filepath.Join(resolvedAllocDir, path)) errors — rare in practice, e.g. extremely long paths exceeding system limits (ENAMETOOLONG) or platform-specific invalid characters on Windows.

Common situations: Client submits a task file path with pathological length; Windows client with illegal path characters; deep directory nesting pushing past MAX_PATH.

Related errors

• failed to resolve alloc directory: %w
• %w: %q
• unable to read rooted allocation directory
• plugin not found
• plugin not executable

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