hashicorp/nomad · error

Failed to parse signal %q

Error message

Failed to parse signal %q

What it means

NewTaskTemplateManager iterates over the task's templates and parses each template's ChangeSignal with signals.Parse. If the signal string is not a valid POSIX signal name (e.g. "SIGFOO", "sigusr1x"), the manager creation fails with this error before any rendering starts.

Source

Thrown at client/allocrunner/taskrunner/template/template.go:206

	// Check pre-conditions
	if err := config.Validate(); err != nil {
		return nil, err
	}

	tm := &TaskTemplateManager{
		config:     config,
		shutdownCh: make(chan struct{}),
	}

	// Parse the signals that we need
	for _, tmpl := range config.Templates {
		if tmpl.ChangeSignal == "" {
			continue
		}

		sig, err := signals.Parse(tmpl.ChangeSignal)
		if err != nil {
			return nil, fmt.Errorf("Failed to parse signal %q", tmpl.ChangeSignal)
		}

		if tm.signals == nil {
			tm.signals = make(map[string]os.Signal)
		}

		tm.signals[tmpl.ChangeSignal] = sig
	}

	// Build the consul-template runner
	runner, lookup, err := templateRunner(config)
	if err != nil {
		return nil, err
	}
	tm.runner = runner
	tm.lookup = lookup

	return tm, nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix `change_signal` in the template stanza to a valid signal name such as SIGHUP, SIGTERM, SIGINT, SIGUSR1, or SIGUSR2.
2. Drop the signal prefix or fix casing if a non-canonical name was used (signals.Parse accepts standard names).
3. Validate signal strings with signals.Parse in job admission/lint tooling before submitting the job.
4. On Windows clients, remove change_signal — it is unsupported there.

Example fix

// before (job HCL)
template { data = "..."; change_signal = "SIGHUPP" }
// after
template { data = "..."; change_signal = "SIGHUP" }

for _, t := range cfg.Templates {
    if t.ChangeSignal == "" { continue }
    if _, err := signals.Parse(t.ChangeSignal); err != nil {
        return fmt.Errorf("template %q has invalid change_signal %q", t.Name, t.ChangeSignal)
    }
}

func validSignal(s string) bool { _, err := signals.Parse(s); return s != "" && err == nil }

tm, err := template.NewTaskTemplateManager(cfg)
if err != nil {
    return fmt.Errorf("creating template manager: %w", err)
}

When it happens

Trigger: A template stanza in the Nomad job sets `change_signal` (tmpl.ChangeSignal) to a string that signals.Parse cannot resolve — misspelled, wrong-case-with-prefix errors, or a signal unsupported on the target platform.

Common situations: Typo in `change_signal = "SIGHUP"` in a job file (e.g. "SIGHUPP"); using a Windows-unsupported signal on a Windows client; dynamic job generation producing malformed signal names.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• All templates should have same Once value
• wait config is nil or empty
• missing datacenter for client registration
• default_identity_ttl must be greater than 0
• max_identity_ttl must be greater than 0

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