{"record":{"id":"c8b0833e95391d92","repo":"hashicorp/nomad","slug":"fingerprinting-failed-v","errorCode":null,"errorMessage":"fingerprinting failed: %v","messagePattern":"fingerprinting failed: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/client.go","lineNumber":477,"sourceCode":"\tc.widsigner = widmgr.NewSigner(widmgr.SignerConfig{\n\t\tNodeSecret: c.secretNodeID(),\n\t\tRegion:     cfg.Region,\n\t\tRPC:        c,\n\t})\n\n\tc.fingerprintManager = NewFingerprintManager(\n\t\tcfg.PluginSingletonLoader,\n\t\tc.GetConfig,\n\t\tcfg.Node,\n\t\tc.shutdownCh,\n\t\tc.updateNodeFromFingerprint,\n\t\tc.logger,\n\t)\n\tc.pluginManagers = pluginmanager.New(c.logger)\n\n\t// Fingerprint the node and scan for drivers\n\tif ir, err := c.fingerprintManager.Run(); err != nil {\n\t\treturn nil, fmt.Errorf(\"fingerprinting failed: %v\", err)\n\t} else {\n\t\tc.topology = numalib.NoImpl(ir.Topology)\n\t}\n\n\t// Create the dynamic workload users pool\n\tc.users = dynamic.New(&dynamic.PoolConfig{\n\t\tMinUGID: cfg.Users.MinDynamicUser,\n\t\tMaxUGID: cfg.Users.MaxDynamicUser,\n\t})\n\n\t// Create the cpu core partition manager\n\tc.partitions = cgroupslib.GetPartition(c.logger.Named(\"partitions\"),\n\t\tc.topology.UsableCores(),\n\t)\n\n\t// Create the process wranglers\n\twranglers, err := proclib.New(&proclib.Configs{\n\t\tUsableCores: c.topology.UsableCores(),","sourceCodeStart":459,"sourceCodeEnd":495,"githubUrl":"https://github.com/hashicorp/nomad/blob/482b49bf1aec006f089bcfc7e632d8f6ac303e5e/client/client.go#L459-L495","documentation":"NewClient returns this when the fingerprint manager's Run() fails. Fingerprinting detects node attributes (CPU, memory, network, cloud metadata) and scans for task drivers; a hard failure here prevents the client from starting with a usable node view.","triggerScenarios":"c.fingerprintManager.Run() returns an error — typically failure to build the node topology (NUMA/CPU detection) or a fatal error during driver detection startup.","commonSituations":"Unusual kernel/CPU environments where numalib topology detection fails (containers, unusual NUMA layouts, restricted /sys access); severely restricted procfs/sysfs in hardened containers; kernel version incompatibilities.","solutions":["Read the wrapped inner error to see which fingerprint module failed.","Run with a more permissive environment (mount /sys, /proc read-only if in a container) or as a host service.","Upgrade Nomad — topology detection improved across releases for containerized and older kernels.","Check the client config for fingerprint/driver allow-deny settings that could interact badly, then retry."],"exampleFix":"// inside a hardened container, before\ndocker run --read-only alpine nomad agent -client\n// after: allow sysfs access\ndocker run -v /sys:/sys:ro -v /proc:/proc:ro nomad agent -client","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"client, err := client.NewClient(cfg, logger)\nif err != nil && strings.Contains(err.Error(), \"fingerprinting failed\") {\n    // surface the wrapped cause to the operator immediately\n    logger.Error(\"client start blocked by fingerprinting\", \"cause\", err)\n    // e.g. check /sys and /proc mounts, kernel version, then restart the agent\n    os.Exit(1)\n}","preventionTips":["In containers, mount /sys and /proc read-only so fingerprinting can detect CPU/memory","Test client startup on canary nodes with unusual NUMA/cgroup layouts before fleet rollout","Keep Nomad current — topology detection (numalib) gains compatibility per release","Avoid nested virtualization/hardened seccomp profiles that hide CPU topology from the agent"],"tags":["client","fingerprinting","initialization"],"backgroundTag":"client-initialization-failed","analyzedSha":"482b49bf1aec006f089bcfc7e632d8f6ac303e5e","analyzedAt":"2026-09-04T07:54:14.808Z","contentChangedAt":"2026-09-04T07:54:14.808Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}