hashicorp/nomad · error

failed to build template manager: %v

Error message

failed to build template manager: %v

What it means

During a job Update (template contents changed in-place), the old template manager is stopped and renderTemplates is called to build a new one. If manager creation fails (e.g. the newManager checks like missing vault config fail), the error is wrapped with this prefix, logged, and the task is killed because templates can no longer render.

Source

Thrown at client/allocrunner/taskrunner/template_hook.go:290

	}

	// neither vault or nomad token has been updated, nothing to do
	if req.VaultToken == h.vaultToken && req.NomadToken == h.nomadToken {
		return nil
	} else {
		h.vaultToken = req.VaultToken
		h.nomadToken = req.NomadToken
	}

	tmpls := h.templateManager.Templates()

	// shutdown the old template
	h.templateManager.Stop()
	h.templateManager = nil

	err := h.renderTemplates(ctx, nil, tmpls)
	if err != nil {
		err = fmt.Errorf("failed to build template manager: %v", err)
		h.logger.Error("failed to build template manager", "error", err)
		_ = h.config.lifecycle.Kill(context.Background(),
			structs.NewTaskEvent(structs.TaskKilling).
				SetFailsTask().
				SetDisplayMessage(fmt.Sprintf("Template update %v", err)))
	}

	return nil
}

// renderTemplates creates the template managers and waits until each template has rendered, setting the watch
// templateManger on the hook when complete so it can be referenced during token updates.
func (h *templateHook) renderTemplates(ctx context.Context, once []*structs.Template, watch []*structs.Template) error {
	onceMgr, unblockOne, err := h.newManager(once)
	if err != nil {
		return err
	}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Fix the underlying cause logged after this prefix (usually vault/consul cluster config missing on clients)
2. Update client agent config with the referenced cluster before nomad job run
3. Stop and resubmit the job fresh if in-place update state is inconsistent
4. Validate the updated template stanza (name, change_mode, source) is well-formed

# validate the UPDATED job before the in-place update
nomad job validate updated.nomad.hcl
nomad job plan updated.nomad.hcl

err := h.renderTemplates(ctx, nil, tmpls)
if err != nil {
    wrapped := fmt.Errorf("failed to build template manager: %w", err)
    h.logger.Error("template update failed; task will be killed", "error", wrapped)
    _ = h.config.lifecycle.Kill(ctx, structs.NewTaskEvent(structs.TaskKilling).SetFailsTask().SetDisplayMessage(wrapped.Error()))
    return wrapped // surface the root cause, not just the wrapper
}

When it happens

Trigger: A live job update changes template blocks such that rebuilding the manager fails — most commonly the updated task references a Vault cluster with no client config (see newManager check) or an invalid consul cluster.

Common situations: Editing a job in place to add/retarget vault or consul blocks without updating client agent configs first; invalid template options introduced in the updated template stanza.

Related errors

• no CNI network config found
• template source path escapes alloc directory
• template destination path escapes alloc directory
• dynamic workload users disabled
• no auth method config or client assertion

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