{"record":{"id":"a3dacb22f60751e2","repo":"henrygd/beszel","slug":"invalid-token","errorCode":null,"errorMessage":"invalid token","messagePattern":"invalid token","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/hub/agent_connect.go","lineNumber":244,"sourceCode":"\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 {\n\t\treturn acr.createNewSystemForUniversalToken(agentFingerprint)\n\t}\n\n\treturn ws.FingerprintRecord{}, errors.New(\"fingerprint mismatch\")\n}\n\n// createNewSystemForUniversalToken creates a new system and fingerprint record for a universal token.\nfunc (acr *agentConnectRequest) createNewSystemForUniversalToken(agentFingerprint common.FingerprintResponse) (ws.FingerprintRecord, error) {\n\tvar fpRecord ws.FingerprintRecord\n\tif !acr.isUniversalToken || acr.userId == \"\" {\n\t\treturn fpRecord, errors.New(\"invalid token\")\n\t}\n\n\tfpRecord.Token = acr.token\n\n\tsystemId, err := acr.createSystem(agentFingerprint)\n\tif err != nil {\n\t\treturn fpRecord, err\n\t}\n\tfpRecord.SystemId = systemId\n\n\t// Set the fingerprint for the new system\n\tif err := acr.hub.SetFingerprint(&fpRecord, agentFingerprint.Fingerprint); err != nil {\n\t\treturn fpRecord, err\n\t}\n\n\t// Update the record with the fingerprint that was set\n\tfpRecord.Fingerprint = agentFingerprint.Fingerprint\n","sourceCodeStart":226,"sourceCodeEnd":262,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/internal/hub/agent_connect.go#L226-L262","documentation":"createNewSystemForUniversalToken re-validates that the request really carries a universal token bound to a user before creating a new system and fingerprint record. If isUniversalToken is false or userId is empty, it refuses with 'invalid token', defending against non-universal tokens silently spawning systems.","triggerScenarios":"handleNoRecords or handleMultipleRecordsOrUniversalToken delegates to createNewSystemForUniversalToken, but the token lacks the universal flag or the request resolved to an empty userId.","commonSituations":"Regular (system-specific) token used by an agent whose system entry was deleted; a universal token not properly linked to a user in the hub database; agents connecting to a hub user account mismatch.","solutions":["Create the system in the hub UI first and use the generated per-system token","If auto-registration is desired, configure the key as a universal token associated with a user","Check the hub database/user association for the token (empty userId indicates orphaned token)","Re-copy the correct KEY from the intended user's system page"],"exampleFix":"// before\nKEY=<plain-system-token-on-unknown-system>\n// after: add the system in hub UI, then\nKEY=<freshly-generated-token>","handlingStrategy":"validation","validationCode":"// verify token kind and ownership before agent start\nif !isUniversalToken(os.Getenv(\"KEY\")) && !systemExistsInHub(key) {\n    log.Fatal(\"add the system in the hub first, or use a universal token\")\n}","typeGuard":null,"tryCatchPattern":"rec, err := acr.createNewSystemForUniversalToken(fp)\nif err != nil && err.Error() == \"invalid token\" {\n    return errors.New(\"token must be a universal token tied to a user\")\n}","preventionTips":["Create systems in the hub UI before starting agents with their tokens","Ensure universal tokens are linked to a non-empty user","Don't reuse system-specific tokens for auto-registration","Review token-user associations after user changes"],"tags":["authentication","universal-token","validation","hub"],"backgroundTag":"invalid-api-token","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}