{"record":{"id":"a7139072178a340b","repo":"henrygd/beszel","slug":"fingerprint-mismatch","errorCode":null,"errorMessage":"fingerprint mismatch","messagePattern":"fingerprint mismatch","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/hub/agent_connect.go","lineNumber":215,"sourceCode":"\treturn acr.createNewSystemForUniversalToken(agentFingerprint)\n}\n\n// handleSingleRecord handles the case with a single fingerprint record. It validates\n// the agent's fingerprint against the stored one, or sets it on first connect.\nfunc (acr *agentConnectRequest) handleSingleRecord(fpRecord ws.FingerprintRecord, agentFingerprint common.FingerprintResponse) (ws.FingerprintRecord, error) {\n\t// If no current fingerprint, update with new fingerprint (first time connecting)\n\tif fpRecord.Fingerprint == \"\" {\n\t\tif err := acr.hub.SetFingerprint(&fpRecord, agentFingerprint.Fingerprint); err != nil {\n\t\t\treturn fpRecord, err\n\t\t}\n\t\t// Update the record with the fingerprint that was set\n\t\tfpRecord.Fingerprint = agentFingerprint.Fingerprint\n\t\treturn fpRecord, nil\n\t}\n\n\t// Abort if fingerprint exists but doesn't match (different machine)\n\tif fpRecord.Fingerprint != agentFingerprint.Fingerprint {\n\t\treturn fpRecord, errors.New(\"fingerprint mismatch\")\n\t}\n\n\treturn fpRecord, nil\n}\n\n// handleMultipleRecordsOrUniversalToken finds a matching fingerprint from multiple records.\n// If no match is found and the token is a universal token, a new system is created.\nfunc (acr *agentConnectRequest) handleMultipleRecordsOrUniversalToken(fpRecords []ws.FingerprintRecord, agentFingerprint common.FingerprintResponse) (ws.FingerprintRecord, error) {\n\t// Return existing record with matching fingerprint if found\n\tfor i := range fpRecords {\n\t\tif fpRecords[i].Fingerprint == agentFingerprint.Fingerprint {\n\t\t\treturn fpRecords[i], nil\n\t\t}\n\t}\n\n\t// No matching fingerprint record found, but it's\n\t// an active universal token so create a new system\n\tif acr.isUniversalToken {","sourceCodeStart":197,"sourceCodeEnd":233,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/internal/hub/agent_connect.go#L197-L233","documentation":"handleSingleRecord finds exactly one fingerprint record for the token. If the record has a fingerprint but it doesn't equal the fingerprint the connecting agent presents, the hub aborts with 'fingerprint mismatch' — the token belongs to a different machine, which could indicate token reuse or a cloned/rebuilt host.","triggerScenarios":"Agent connects; its token resolves to a single stored record whose Fingerprint differs from agentFingerprint.Fingerprint (e.g. agent reinstalled, container recreated, or key copied to a second machine).","commonSituations":"Copying the same KEY to multiple agents; recreating a Docker container so its generated fingerprint changed; disk reinstall or hardware change; agent moved to a different host without re-adding the system in the hub.","solutions":["Remove the system in the hub and re-add it so the new fingerprint is accepted with a fresh token","If the fingerprint changed legitimately (container rebuilt), update/reset the stored fingerprint record","Ensure the KEY is unique per system — never share one token across agents","Check that a proxy isn't routing two different agents through one system entry"],"exampleFix":"// before: same KEY on two machines\nKEY=<shared-key> on host-a and host-b\n// after: unique key per system\nhost-a: KEY=<token-a>\nhost-b: KEY=<token-b>","handlingStrategy":"validation","validationCode":"// ensure each host has its own key before deploy\nif keyInUseOnAnotherHost(agentKey) {\n    log.Fatal(\"KEY already bound to another system; generate a new one\")\n}","typeGuard":null,"tryCatchPattern":"rec, err := acr.handleSingleRecord(fp)\nif err != nil && err.Error() == \"fingerprint mismatch\" {\n    // recreate container/hardware change: re-add the system in hub\n    return reRegisterSystem()\n}","preventionTips":["Never reuse one KEY across multiple agents","After rebuilding a container/VM or reinstalling, re-add the system in the hub","Store keys per-host in your config management, not shared templates","Watch for cloned disk images carrying stale keys"],"tags":["authentication","fingerprint","security","token-reuse"],"backgroundTag":"fingerprint-mismatch","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}