hashicorp/nomad · critical

pre-run hook %q failed: %v

Error message

pre-run hook %q failed: %v

What it means

While starting an allocation, the prerun phase runs each lifecycle pre-run hook (alloc directory, task runners setup, scripts, etc.). If any hook's Prerun returns an error, prerun aborts immediately and wraps it with the hook name and cause. The alloc fails and is rescheduled depending on failure handling settings.

Source

Thrown at client/allocrunner/alloc_runner_hooks.go:196

		name := pre.Name()
		var start time.Time
		if ar.logger.IsTrace() {
			start = time.Now()
			ar.logger.Trace("running pre-run hook", "name", name, "start", start)
		}

		// If the operator has disabled hook metrics, then don't call the time
		// function to save 30ns per hook.
		var hookExecutionStart time.Time

		if !ar.clientConfig.DisableAllocationHookMetrics {
			hookExecutionStart = time.Now()
		}

		err := pre.Prerun(allocEnv)
		ar.hookStatsHandler.Emit(hookExecutionStart, name, "prerun", err)
		if err != nil {
			return fmt.Errorf("pre-run hook %q failed: %v", name, err)
		}

		if ar.logger.IsTrace() {
			end := time.Now()
			ar.logger.Trace("finished pre-run hook", "name", name, "end", end, "duration", end.Sub(start))
		}
	}

	return nil
}

// update runs the alloc runner update hooks. Update hooks are run
// asynchronously with all other alloc runner operations.
func (ar *allocRunner) update(update *structs.Allocation) error {
	if ar.logger.IsTrace() {
		start := time.Now()
		ar.logger.Trace("running update hooks", "start", start)
		defer func() {

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Read the hook name in the message and the wrapped cause (e.g. image pull failure, mkdir permission denied)
2. Check disk space and permissions on the client's data_dir/alloc_dir
3. Verify referenced host volumes, artifacts, and container images are reachable/valid
4. Use `nomad alloc status` and client logs for the failing hook's detailed error; fix root cause and reschedule

// preflight checks before deploy
df -h /var/lib/nomad   // disk space
ls -ld $NOMAD_DATA_DIR/alloc // permissions
curl -I $ARTIFACT_URL // artifacts reachable

if _, err := client.Allocations().Info(ctx, allocID, nil); err != nil {
  // inspect alloc events for the failing hook name
  for _, ev := range alloc.TaskEvents { log.Printf("%s: %s", ev.Type, ev.DisplayMessage) }
}

When it happens

Trigger: Any hook registered in initRunnerHooks whose Prerun(allocEnv) errors — e.g. mkdir/persist of alloc/task directories fails, script hooks fail, task runner prerun (image pull, chroot setup) fails.

Common situations: Disk full or permissions issues on data_dir/alloc_dir; Docker image pull failures; host volume paths not existing or unreadable; SELinux/AppArmor denials; NFS mount problems on the client host.

Related errors

• update hook %q failed: %v
• post-run hook %q failed: %w
• no servers
• users: release of unused uid/gid
• missing node ID

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