{"record":{"id":"d68df33792ebd7f8","repo":"henrygd/beszel","slug":"no-matching-fingerprints","errorCode":null,"errorMessage":"no matching fingerprints","messagePattern":"no matching fingerprints","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/hub/agent_connect.go","lineNumber":194,"sourceCode":"\t\treturn acr.handleNoRecords(agentFingerprint)\n\t}\n\n\t// Single record - handle as regular token\n\tif len(fpRecords) == 1 && !acr.isUniversalToken {\n\t\treturn acr.handleSingleRecord(fpRecords[0], agentFingerprint)\n\t}\n\n\t// Multiple records or universal token - look for matching fingerprint\n\treturn acr.handleMultipleRecordsOrUniversalToken(fpRecords, agentFingerprint)\n}\n\n// handleNoRecords handles the case where no fingerprint records are found for a token.\n// A new system is created if the token is a valid universal token.\nfunc (acr *agentConnectRequest) handleNoRecords(agentFingerprint common.FingerprintResponse) (ws.FingerprintRecord, error) {\n\tvar fpRecord ws.FingerprintRecord\n\n\tif !acr.isUniversalToken || acr.userId == \"\" {\n\t\treturn fpRecord, errors.New(\"no matching fingerprints\")\n\t}\n\n\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","sourceCodeStart":176,"sourceCodeEnd":212,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/internal/hub/agent_connect.go#L176-L212","documentation":"handleNoRecords fires when the hub finds no fingerprint records associated with the presented token. A new system is auto-created only if the token is a valid universal token tied to a user; otherwise the connection is rejected. This prevents unknown tokens from registering systems.","triggerScenarios":"An agent presents a token that has no fingerprint records in the database and the token is not flagged universal (or the resolved userId is empty).","commonSituations":"System was deleted in the hub while the agent still holds the old key; agent pointed at the wrong hub whose database has no such token; token copied from a different user's account; multi-user setup where the token wasn't issued as a universal key.","solutions":["Verify the agent's KEY matches a token defined in the hub for the target user","Re-add the system in the hub and update the agent's KEY to the freshly generated token","If using a universal token, confirm it's configured as such and associated with a user (not empty userId)","Confirm the agent is connecting to the correct hub URL"],"exampleFix":"// before\nKEY=<old-key-from-deleted-system>\n// after: regenerate in hub UI → Add System, then\nKEY=<new-token> ./beszel-agent","handlingStrategy":"retry","validationCode":"// preflight: confirm the token exists in the hub for this user\nsystems := hub.ListSystems(token)\nif len(systems) == 0 && !isUniversalToken(token) {\n    log.Fatal(\"token unknown to hub; re-add the system and copy the new KEY\")\n}","typeGuard":null,"tryCatchPattern":"rec, err := acr.handleNoRecords(fp)\nif err != nil && err.Error() == \"no matching fingerprints\" {\n    // re-register: add system in hub UI, restart agent with new KEY\n    return retryWithNewKey()\n}","preventionTips":["Regenerate KEY whenever a system is deleted/re-added in the hub","Point agents at the correct hub instance","Use universal tokens only for intentional auto-registration","Keep one token per user account to avoid cross-user confusion"],"tags":["authentication","fingerprint","token","hub"],"backgroundTag":"token-not-recognized","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}