hashicorp/nomad · error

%v: %s

Error message

%v: %s

What it means

This error wraps a template sandbox execution failure in Nomad's template runner. When readTemplateFromSandbox returns an error with a non-zero exit code, the raw stderr output from the template-rendering subprocess (consul-template) is appended to the error via fmt.Errorf. The developer sees both the underlying error and the subprocess's own diagnostic output.

Source

Thrown at client/allocrunner/taskrunner/template/template_default.go:183

func ReaderFn(taskID, taskDir string, sandboxEnabled bool) func(string) ([]byte, error) {
	if !sandboxEnabled {
		return nil
	}
	thisBin := subproc.Self()

	return func(src string) ([]byte, error) {

		sandboxCfg := &sandboxConfig{
			thisBin:     thisBin,
			sandboxPath: taskDir,
			sourcePath:  src,
			taskID:      taskID,
		}

		stdout, stderr, code, err := readTemplateFromSandbox(sandboxCfg)
		if err != nil && code != 0 {
			return nil, fmt.Errorf("%v: %s", err, string(stderr))
		}

		// this will get wrapped in CT log formatter
		fmt.Fprintf(os.Stderr, "[DEBUG] %s", string(stderr))
		return stdout, nil
	}
}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the stderr portion of the error — it contains consul-template's actual diagnostic
2. Validate template syntax locally with the consul-template CLI before deploying
3. Verify consul/vault blocks in the task and the client agent's consul/vault configs are correct
4. Check task logs for the [DEBUG] line that mirrors the same stderr

# validate template/job before deploy
nomad job validate job.nomad.hcl
# validate template rendering locally
consul-template -template 'tpl.ctmpl:/tmp/out' -once

stdout, stderr, code, err := readTemplateFromSandbox(sandboxCfg)
if err != nil && code != 0 {
    // stderr carries the consul-template diagnostic — surface it, don't swallow it
    return nil, fmt.Errorf("template render failed: %w: %s", err, string(stderr))
}

When it happens

Trigger: readTemplateFromSandbox fails AND the sandbox command exits with code != 0, e.g. the consul-template binary fails to render a template due to syntax errors, missing secrets, or consul/vault connectivity failures inside the task sandbox.

Common situations: Malformed template syntax, references to undefined variables, consul-template being unable to reach Consul/Vault agents from within the sandbox, or missing permissions on the sandbox directory.

Related errors

• Invalid task directory given: %q
• Invalid task environment given
• All templates should have same Once value
• template source path escapes alloc directory
• template destination path escapes alloc directory

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