hashicorp/nomad · error

error fingerprinting plugin %q: %w

Error message

error fingerprinting plugin %q: %w

What it means

Fingerprint runs the external plugin executable with the "fingerprint" operation and captures stdout/stderr. If the plugin process itself fails to run or exits with an error, Nomad logs it and returns this wrapped error naming the plugin ID. This is a wrapper around the plugin's execution failure — the real cause (non-zero exit, exec format error, timeout, crash) is in the wrapped error.

Source

Thrown at client/hostvolumemanager/host_volume_plugin.go:295

// {"version": "0.0.1"}
// The version value should be a valid version number as allowed by
// version.NewVersion()
//
// Must complete within 5 seconds
func (p *HostVolumePluginExternal) Fingerprint(ctx context.Context) (*PluginFingerprint, error) {
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()
	cmd := exec.CommandContext(ctx, p.Executable, "fingerprint")
	cmd.Env = []string{EnvOperation + "=fingerprint"}
	stdout, stderr, err := runCommand(cmd)
	log := p.log.With(
		"operation", "fingerprint",
		"stdout", string(stdout),
		"stderr", string(stderr),
	)
	if err != nil {
		log.Error("error running plugin", "error", err)
		return nil, fmt.Errorf("error fingerprinting plugin %q: %w", p.ID, err)
	}
	fprint := &PluginFingerprint{}
	if err := json.Unmarshal(stdout, fprint); err != nil {
		err = fmt.Errorf("error parsing fingerprint output as json: %w", err)
		log.Error("error parsing plugin output", "error", err)
		return nil, err
	}
	return fprint, nil
}

// Create calls the executable with the following parameters:
// arguments: $1=create
// environment:
// - DHV_OPERATION=create
// - DHV_VOLUMES_DIR={directory to put the volume in}
// - DHV_PLUGIN_DIR={path to directory containing plugins}
// - DHV_NAMESPACE={volume namespace}
// - DHV_VOLUME_NAME={name from the volume specification}

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run the plugin binary manually with its fingerprint argument to reproduce the underlying failure and read its stderr.
2. Check the wrapped error: exec format error means wrong architecture — rebuild/re-download the plugin for the node's OS/arch.
3. Verify the interpreter in the plugin script's shebang exists on the node.
4. Confirm the plugin implements the fingerprint protocol and exits 0 while printing valid JSON to stdout.

Example fix

// before: shebang points to absent interpreter
#!/usr/bin/python3  # python3 not installed on node -> exec fails

// after
#!/usr/bin/env bash  # or install python3 on the node

func probePluginFingerprint(executable string) error {
    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    cmd := exec.CommandContext(ctx, executable, "fingerprint")
    var stderr bytes.Buffer
    cmd.Stderr = &stderr
    if err := cmd.Run(); err != nil {
        return fmt.Errorf("plugin fingerprint probe failed: %w; stderr: %s", err, stderr.String())
    }
    return nil
}

if err != nil && strings.Contains(err.Error(), "error fingerprinting plugin") {
    var exitErr *exec.ExitError
    if errors.As(err, &exitErr) {
        log.Error("plugin exited non-zero", "code", exitErr.ExitCode(), "stderr", string(exitErr.Stderr))
    } else if errors.Is(err, exec.ErrNotFound) || strings.Contains(err.Error(), "exec format error") {
        log.Error("wrong arch/interpreter for plugin binary")
    }
}

When it happens

Trigger: Calling Fingerprint on a HostVolumePluginExternal when the child process invocation fails: plugin exits non-zero, binary has a bad shebang or wrong architecture (exec format error), plugin crashes, or the plugin writes malformed output causing a transport-level failure.

Common situations: Plugin binary built for the wrong OS/arch on the client node; plugin script with a shebang pointing to a missing interpreter (e.g. #!/usr/bin/python3 not installed); plugin itself erroring due to missing local configuration or dependencies; plugin killing itself on startup.

Related errors

• error parsing fingerprint output as json: %w
• %w: %q
• ErrPluginNotExists
• ErrPluginNotExecutable
• ErrVolumeNameExists

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