hashicorp/nomad · error

failed to fingerprint plugins: %v

Error message

failed to fingerprint plugins: %v

What it means

Once binaries are scanned, fingerprintPlugins runs each candidate binary (the loader launches it with a fingerprint argument) to detect its API version and plugin type. Failures here—binary that won't exec, crashes, bad exit, unreadable file—are wrapped with this message and abort construction.

Source

Thrown at helper/pluginutils/loader/init.go:76

	// Create a mapping of name to config
	configMap := configMap(cfg.Configs)

	// Initialize the internal plugins
	internal, err := l.initInternal(cfg.InternalPlugins, configMap)
	if err != nil {
		return nil, fmt.Errorf("failed to fingerprint internal plugins: %v", err)
	}

	// Scan for eligibile binaries
	plugins, err := l.scan()
	if err != nil {
		return nil, fmt.Errorf("failed to scan plugin directory %q: %v", l.pluginDir, err)
	}

	// Fingerprint the passed plugins
	external, err := l.fingerprintPlugins(plugins, configMap)
	if err != nil {
		return nil, fmt.Errorf("failed to fingerprint plugins: %v", err)
	}

	// Merge external and internal plugins
	l.plugins = l.mergePlugins(internal, external)

	// Validate that the configs are valid for the plugins
	canonicalizedConfigs, err := l.validatePluginConfigs()
	if err != nil {
		return nil, fmt.Errorf("parsing plugin configurations failed: %v", err)
	}

	for i := range configMap {
		if updated, ok := canonicalizedConfigs[i]; ok {
			configMap[i].Config = updated.Config
		}
	}

	return configMap, nil

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Run the failing binary manually (path shown by enabling loader logs) to see the exec error.
2. Re-download/rebuild the plugin for the host GOOS/GOARCH and verify with `file <binary>`.
3. Check mount flags (noexec) and security modules (SELinux) that block execution.
4. Remove incompatible binaries from the plugin directory if they are not needed.

Example fix

// before
$ curl -o /opt/plugins/my-plugin https://example.com/my-plugin  # may fetch HTML

// after
$ curl -fSL -o /opt/plugins/my-plugin https://example.com/my-plugin
$ chmod +x /opt/plugins/my-plugin && file /opt/plugins/my-plugin

entries, err := os.ReadDir(cfg.PluginDir)
if err != nil {
    return err
}
for _, e := range entries {
    p := filepath.Join(cfg.PluginDir, e.Name())
    if err := exec.Command(p, "-version").Run(); err != nil {
        return fmt.Errorf("plugin %q not executable on this host: %w", p, err)
    }
}

loader, err := NewPluginLoader(cfg)
if err != nil {
    if strings.Contains(err.Error(), "failed to fingerprint plugins") {
        logger.Warn("plugin fingerprinting failed; check binaries", "err", err)
        return fmt.Errorf("repair or remove incompatible plugin binaries: %w", err)
    }
    return err
}

When it happens

Trigger: A file in the plugin dir is not a valid executable for the host (wrong architecture, script without shebang, corrupted binary); the plugin binary crashes during fingerprinting; timeout on the fingerprint handshake.

Common situations: Copying plugins built for a different OS/arch (linux/amd64 binary on arm64); downloading a plugin over HTTP that got an HTML error page instead of a binary; SELinux or noexec mount preventing execution; plugin built against an incompatible plugin API version.

Related errors

• failed to fingerprint internal plugins: %v
• ErrPluginNotExecutable
• %w: %w
• failed to determine mount point for %s
• plugin config passed without binary name

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