hashicorp/nomad · error

executor Shutdown failed: %v

Error message

executor Shutdown failed: %v

What it means

StopTask sends a shutdown signal to the task's executor and waits up to the given timeout for graceful termination. If executor.Shutdown returns an error, the driver reports 'executor Shutdown failed'. If the plugin client has already exited, the error is swallowed since the task is already gone.

Source

Thrown at drivers/exec/driver.go:630

	case <-ctx.Done():
		return
	case <-d.ctx.Done():
		return
	case ch <- result:
	}
}

func (d *Driver) StopTask(taskID string, timeout time.Duration, signal string) error {
	handle, ok := d.tasks.Get(taskID)
	if !ok {
		return drivers.ErrTaskNotFound
	}

	if err := handle.exec.Shutdown(signal, timeout); err != nil {
		if handle.pluginClient.Exited() {
			return nil
		}
		return fmt.Errorf("executor Shutdown failed: %v", err)
	}

	return nil
}

func (d *Driver) DestroyTask(taskID string, force bool) error {
	handle, ok := d.tasks.Get(taskID)
	if !ok {
		return drivers.ErrTaskNotFound
	}

	if handle.IsRunning() && !force {
		return fmt.Errorf("cannot destroy running task")
	}

	if !handle.pluginClient.Exited() {
		if err := handle.exec.Shutdown("", 0); err != nil {
			handle.logger.Error("destroying executor failed", "error", err)

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Retry StopTask; if the process remains, the subsequent DestroyTask (force) will tear it down.
2. Increase the task's kill_timeout so the application has time to handle the shutdown signal.
3. Ensure the application handles SIGTERM (or the configured kill signal) and exits promptly.
4. Check executor logs for why the signal or wait failed (permissions, zombie process, plugin crash).

if err := driver.StopTask(taskID, timeout, signal); err != nil {
    if strings.Contains(err.Error(), "executor Shutdown failed") {
        // escalate: force destroy
        _ = driver.DestroyTask(taskID, true)
    }
}

When it happens

Trigger: Calling driver.StopTask(taskID, timeout, signal) while the executor is alive but executor.Shutdown(signal, timeout) returns an error (signal delivery failed or the process did not exit within timeout).

Common situations: Task ignores SIGTERM and outlives the kill_timeout; executor process wedged or unresponsive; insufficient permissions to signal the process; stopping tasks during client shutdown.

Related errors

• default_pid_mode must be %q or %q, got %q
• default_ipc_mode must be %q or %q, got %q
• allow_caps configured with capabilities not supported by sys
• pid_mode must be %q or %q, got %q
• ipc_mode must be %q or %q, got %q

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