hashicorp/nomad · error

unknown fingerprint '%s'

Error message

unknown fingerprint '%s'

What it means

NewFingerprint looks up a fingerprint factory by name in the hostFingerprinters and envFingerprinters maps. If the configured name matches neither, it returns this error. This happens when a fingerprint name in the client config's options ("fingerprint.allowlist"/"denylist" or the deprecated fingerprint list) is not a known builtin.

Source

Thrown at client/fingerprint/fingerprint.go:86

	for k := range hostFingerprinters {
		fingerprints = append(fingerprints, k)
	}
	sort.Strings(fingerprints)
	for k := range envFingerprinters {
		fingerprints = append(fingerprints, k)
	}
	return fingerprints
}

// NewFingerprint is used to instantiate and return a new fingerprint
// given the name and a logger
func NewFingerprint(name string, logger log.Logger) (Fingerprint, error) {
	// Lookup the factory function
	factory, ok := hostFingerprinters[name]
	if !ok {
		factory, ok = envFingerprinters[name]
		if !ok {
			return nil, fmt.Errorf("unknown fingerprint '%s'", name)
		}
	}

	// Instantiate the fingerprint
	f := factory(logger)
	return f, nil
}

// Factory is used to instantiate a new Fingerprint
type Factory func(log.Logger) Fingerprint

// HealthCheck is used for doing periodic health checks. On a given time
// interfal, a health check will be called by the fingerprint manager of the
// node.
type HealthCheck interface {
	// Check is used to update properties of the node on the status of the health
	// check
	HealthCheck(*cstructs.HealthCheckRequest, *cstructs.HealthCheckResponse) error

View on GitHub (pinned to 482b49bf1a)

Solutions

1. Check the fingerprint name against the builtins (host: arch, cpu, memory, disk, storage, network, consul, vault, nomad, cni, etc.; env: aws, gce, azure, digitalocean)
2. Fix the typo or remove the unknown entry from the allowlist/denylist in client config
3. Match the names to your Nomad version's documentation (names changed across releases)
4. Verify only the short names are used (e.g. "consul", not "consul_fingerprint")

Example fix

// before
client {
  options {
    "fingerprint.allowlist" = "aws,env_aws" // env_aws is not a valid name
  }
}
// after
client {
  options {
    "fingerprint.allowlist" = "aws,consul"
  }
}

var knownFingerprints = map[string]bool{"arch":true,"cpu":true,"memory":true,"disk":true,"storage":true,"network":true,"cni":true,"consul":true,"vault":true,"nomad":true,"aws":true,"gce":true,"azure":true,"digitalocean":true}
for _, name := range configuredFingerprints {
    if !knownFingerprints[name] { return fmt.Errorf("unknown fingerprint %q", name) }
}

When it happens

Trigger: Client config lists a fingerprint name that doesn't exist (typo, removed fingerprint, custom name, wrong casing) during setupFingerprinters at client startup.

Common situations: Typo like "env_aws" vs actual name "aws"; fingerprint renamed across Nomad versions (e.g. old names removed); copy-pasted config from a different Nomad version; hand-written allowlists.

Related errors

• No nomad log file defined
• consul address must be set on nomad client
• no CNI network config found
• fingerprint name cannot be empty
• empty response from AWS metadata

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