hashicorp/nomad · error

Error reading %q: %w

Error message

Error reading %q: %w

What it means

In the 'var put' flow, an argument like '@specfile' (or the designated spec path) makes the command read the entire variable specification from that file via os.ReadFile. This error wraps the read failure with the offending path, preserving the underlying OS error through %w.

Source

Thrown at command/var_lock.go:304

	var path string

	// Handle first argument:  @file or «var path»
	arg := args[0]

	switch {
	case isArgFileRef(arg):
		// ArgFileRefs start with "@" so we need to peel that off
		// detect format based on file extension
		specPath := arg[1:]
		err = c.varPutCommand.setParserForFileArg(specPath)
		if err != nil {
			return "", args, err
		}

		c.varPutCommand.verbose(fmt.Sprintf("Reading whole variable specification from %q", specPath))
		c.varPutCommand.contents, err = os.ReadFile(specPath)
		if err != nil {
			return "", args, fmt.Errorf("Error reading %q: %w", specPath, err)
		}
	default:
		path = sanitizePath(arg)
		c.varPutCommand.verbose(fmt.Sprintf("Writing to path %q", path))
	}

	// Handle second argument: can @file, or child process
	args = args[1:]
	switch {
	case isArgFileRef(args[0]):
		arg := args[0]

		err = c.varPutCommand.setParserForFileArg(arg)
		if err != nil {
			return "", args, err
		}

		c.varPutCommand.verbose(fmt.Sprintf("Creating variable %q from specification file %q", path, arg))

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Verify the spec file path exists relative to the current working directory and is a regular file (ls -la <path>)
2. Use an absolute path to eliminate CWD ambiguity
3. Check read permissions for the invoking user, especially in CI containers
4. If the spec is generated by an earlier step, ensure that step completed before running var put

Example fix

// before
waypoint var put @deploy.vars   // deploy.vars missing in CI workspace
// after
waypoint var put @${CI_WORKSPACE}/deploy.vars   // absolute, verified to exist

if fi, err := os.Stat(specPath); err != nil {
	// fail fast: spec file missing
} else if fi.IsDir() {
	// fail fast: spec path is a directory
}

contents, err := os.ReadFile(specPath)
if err != nil {
	if errors.Is(err, fs.ErrNotExist) { /* generate or locate spec */ }
	if errors.Is(err, fs.ErrPermission) { /* fix permissions */ }
}

When it happens

Trigger: Running `waypoint var put @myspec.hcl` (or the equivalent readPathFromArgs path) where myspec.hcl does not exist, is unreadable, or is a directory. Raised from readPathFromArgs during Run.

Common situations: Typo'd spec file names; executing the command from a different working directory than the spec file's location; CI checkouts where the spec file was not committed or not yet generated; permission-restricted files.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• error reading file: %w
• error reading %q: %s
• not a terminal
• both -n and -c set
• Allocation %q is running the following tasks: * %s Please

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