hashicorp/nomad · error

failed to build ReattachConfig from taskConfig state: %v

Error message

failed to build ReattachConfig from taskConfig state: %v

What it means

This error is returned by RecoverTask when pstructs.ReattachConfigToGoPlugin cannot build a valid go-plugin ReattachConfig from the stored ReattachConfig in the task state. The stored config lacks required fields (protocol, address, PID, etc.) or uses an unsupported protocol version. Without a valid reattach config the driver cannot reconnect to the executor plugin.

Source

Thrown at drivers/java/driver.go:401

	// If already attached to handle there's nothing to recover.
	if _, ok := d.tasks.Get(handle.Config.ID); ok {
		d.logger.Debug("nothing to recover; task already exists",
			"task_id", handle.Config.ID,
			"task_name", handle.Config.Name,
		)
		return nil
	}

	var taskState TaskState
	if err := handle.GetDriverState(&taskState); err != nil {
		d.logger.Error("failed to decode taskConfig state from handle", "error", err, "task_id", handle.Config.ID)
		return fmt.Errorf("failed to decode taskConfig state from handle: %v", err)
	}

	plugRC, err := pstructs.ReattachConfigToGoPlugin(taskState.ReattachConfig)
	if err != nil {
		d.logger.Error("failed to build ReattachConfig from taskConfig state", "error", err, "task_id", handle.Config.ID)
		return fmt.Errorf("failed to build ReattachConfig from taskConfig state: %v", err)
	}

	execImpl, pluginClient, err := executor.ReattachToExecutor(
		plugRC,
		d.logger.With("task_name", handle.Config.Name, "alloc_id", handle.Config.AllocID),
		d.nomadConfig.Topology.Compute(),
	)

	if err != nil {
		d.logger.Error("failed to reattach to executor", "error", err, "task_id", handle.Config.ID)
		return fmt.Errorf("failed to reattach to executor: %v", err)
	}

	h := &taskHandle{
		exec:         execImpl,
		pid:          taskState.Pid,
		pluginClient: pluginClient,
		taskConfig:   taskState.TaskConfig,

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Stop and restart the affected allocation so a fresh executor is launched
2. Verify the Nomad agent and executor plugin versions match (no mixed-version cluster during rolling upgrade)
3. Check the client logs for the underlying ReattachConfigToGoPlugin error detail
4. Restore valid client state or clear the corrupted allocation state

Example fix

// remediation: recreate the allocation rather than reattach
// nomad alloc stop <alloc_id> && nomad job eval <job_id>

if err := driver.RecoverTask(handle); err != nil {
    if strings.Contains(err.Error(), "failed to build ReattachConfig") {
        // recreate the allocation instead of reattaching
        _ = client.Allocations().Stop(ctx, alloc, nil)
    }
}

When it happens

Trigger: TaskState.ReattachConfig is nil or incomplete (e.g. state persisted before the executor plugin fully started), or the stored protocol/addr fields cannot be converted to a go-plugin client config.

Common situations: Recovering allocations right after an agent crash where reattach info was never fully written; plugin protocol version mismatches after Nomad upgrades; manual state edits.

Related errors

• failed to reattach to executor: %v
• failed to build ReattachConfig from taskConfig state: %v
• handle cannot be nil
• failed to decode taskConfig state from handle: %v
• failed to create executor: %v

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