hashicorp/nomad · error

executor failed to find process: %v

Error message

executor failed to find process: %v

What it means

Wraps an error from os.FindProcess(e.childCmd.Process.Pid) during Shutdown. On Unix FindProcess rarely fails (it just returns a Process handle), so this usually indicates a system-level failure resolving the PID; on Windows it means the process no longer exists. The PID from the child command could not be resolved for signaling.

Source

Thrown at drivers/shared/executor/executor.go:633

// kills the user process.
func (e *UniversalExecutor) Shutdown(signal string, grace time.Duration) error {
	e.logger.Debug("shutdown requested", "signal", signal, "grace_period_ms", grace.Round(time.Millisecond))
	var merr multierror.Error

	// If the executor did not launch a process, return.
	if e.command == nil {
		return nil
	}

	// If there is no process we can't shutdown
	if e.childCmd.Process == nil {
		e.logger.Warn("failed to shutdown due to missing process", "error", "no process found")
		return fmt.Errorf("executor failed to shutdown error: no process found")
	}

	proc, err := os.FindProcess(e.childCmd.Process.Pid)
	if err != nil {
		err = fmt.Errorf("executor failed to find process: %v", err)
		e.logger.Warn("failed to shutdown due to inability to find process", "pid", e.childCmd.Process.Pid, "error", err)
		return err
	}

	// If grace is 0 then skip shutdown logic
	if grace > 0 {
		// Default signal to SIGINT if not set
		if signal == "" {
			signal = "SIGINT"
		}

		sig, ok := signals.SignalLookup[signal]
		if !ok {
			err = fmt.Errorf("error unknown signal given for shutdown: %s", signal)
			e.logger.Warn("failed to shutdown", "error", err)
			return err
		}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the wrapped inner error (%v) for the OS-level cause
2. If the process already exited, treat shutdown as complete and proceed to cleanup
3. Verify client and task share the expected PID namespace (avoid hiding task PIDs from the client)
4. Retry Shutdown once; transient PID-resolution failures are rare

Example fix

// before
if err := exec.Shutdown(); err != nil {
    return err
}
// after
if err := exec.Shutdown(); err != nil {
    if strings.Contains(err.Error(), "failed to find process") {
        logger.Warn("task process already gone; skipping graceful shutdown")
        return nil
    }
    return err
}

// Verify PID is visible before shutdown
if pid > 0 {
    if _, err := os.FindProcess(pid); err != nil {
        return nil // process already gone
    }
    // On unix, optionally check /proc/<pid> existence
    if _, err := os.Stat(fmt.Sprintf("/proc/%d", pid)); os.IsNotExist(err) {
        return nil
    }
}

func pidAlive(pid int) bool {
    if pid <= 0 { return false }
    proc, err := os.FindProcess(pid)
    if err != nil { return false }
    return proc.Signal(syscall.Signal(0)) == nil
}

if err := exec.Shutdown(); err != nil {
    if strings.Contains(err.Error(), "failed to find process") {
        log.Info("process already gone; skipping graceful shutdown")
        return nil
    }
    return err
}

When it happens

Trigger: Calling Shutdown when the child process already exited and was reaped (Windows) or the OS refused the PID lookup (resource issues, PID namespace mismatch).

Common situations: Task exited just before shutdown; container/PID-namespace boundary so the PID is invisible; Windows host where the process handle is gone.

Related errors

• executor Shutdown failed: %v
• executor: error waiting on process: %v
• executor Shutdown failed: %v
• executor failed to shutdown error: no process found
• error unknown signal given for shutdown: %s

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