{"record":{"id":"01cb7245f73f764e","repo":"henrygd/beszel","slug":"hub-not-verified","errorCode":null,"errorMessage":"hub not verified","messagePattern":"hub not verified","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"agent/handlers.go","lineNumber":72,"sourceCode":"\n\treturn registry\n}\n\n// Register registers a handler for a specific action type\nfunc (hr *HandlerRegistry) Register(action common.WebSocketAction, handler RequestHandler) {\n\thr.handlers[action] = handler\n}\n\n// Handle routes the request to the appropriate handler\nfunc (hr *HandlerRegistry) Handle(hctx *HandlerContext) error {\n\thandler, exists := hr.handlers[hctx.Request.Action]\n\tif !exists {\n\t\treturn fmt.Errorf(\"unknown action: %d\", hctx.Request.Action)\n\t}\n\n\t// Check verification requirement - default to requiring verification\n\tif hctx.Request.Action != common.CheckFingerprint && !hctx.HubVerified {\n\t\treturn errors.New(\"hub not verified\")\n\t}\n\n\t// Log handler execution for debugging\n\t// slog.Debug(\"Executing handler\", \"action\", hctx.Request.Action)\n\n\treturn handler.Handle(hctx)\n}\n\n// GetHandler returns the handler for a specific action\nfunc (hr *HandlerRegistry) GetHandler(action common.WebSocketAction) (RequestHandler, bool) {\n\thandler, exists := hr.handlers[action]\n\treturn handler, exists\n}\n\n////////////////////////////////////////////////////////////////////////////\n////////////////////////////////////////////////////////////////////////////\n\n// GetDataHandler handles system data requests","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/agent/handlers.go#L54-L90","documentation":"Handle dispatches incoming hub requests to registered action handlers. Except for the CheckFingerprint action, every request requires the hub to have completed verification (hctx.HubVerified). This error is returned when a non-fingerprint action arrives before verification succeeded, preventing unauthenticated hub commands from running.","triggerScenarios":"The agent's Handle is invoked with hctx.HubVerified == false and hctx.Request.Action set to anything other than common.CheckFingerprint — e.g. a hub sends commands before the fingerprint handshake completes, or verification failed silently on the agent.","commonSituations":"Hub/agent version mismatch where the hub skips or breaks the fingerprint verification exchange; key or fingerprint mismatch after regenerating the hub's SSH keys; clock/network issues interrupting the handshake; manually poking the agent's socket before pairing.","solutions":["Restart both hub and agent so the fingerprint verification handshake runs from scratch.","Verify the agent's fingerprint file matches what the hub expects; delete the agent's fingerprint file to re-pair if the hub keys changed.","Check hub and agent versions are compatible (fingerprint verification flow changed across releases).","Inspect agent logs for earlier verification errors (e.g. fingerprint or SSH errors) that left HubVerified false."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"err := handle(hctx)\nif err != nil && err.Error() == \"hub not verified\" {\n    log.Warn(\"request rejected pre-verification; re-running fingerprint handshake\")\n    if err := verifyFingerprint(); err != nil {\n        log.Fatalf(\"verification failed: %v\", err)\n    }\n}","preventionTips":["Always complete the CheckFingerprint exchange before sending any other actions.","Keep hub and agent versions aligned so the handshake protocol matches.","After regenerating hub keys, re-pair agents (delete stale fingerprint files).","Only send non-fingerprint actions after a verified session is established."],"tags":["authentication","handshake","security","hub"],"backgroundTag":"hub-not-verified","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}