{"record":{"id":"c7ba6e206d7d1273","repo":"henrygd/beszel","slug":"unknown-action-d","errorCode":null,"errorMessage":"unknown action: %d","messagePattern":"unknown action: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"agent/handlers.go","lineNumber":67,"sourceCode":"\tregistry.Register(common.CheckFingerprint, &CheckFingerprintHandler{})\n\tregistry.Register(common.GetContainerLogs, &GetContainerLogsHandler{})\n\tregistry.Register(common.GetContainerInfo, &GetContainerInfoHandler{})\n\tregistry.Register(common.GetSmartData, &GetSmartDataHandler{})\n\tregistry.Register(common.GetSystemdInfo, &GetSystemdInfoHandler{})\n\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}","sourceCodeStart":49,"sourceCodeEnd":85,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/agent/handlers.go#L49-L85","documentation":"The agent's HandlerRegistry.Handle returns this when the incoming WebSocket request's Action value has no registered handler. It signals a protocol mismatch between hub and agent — the hub sent an action this agent build doesn't recognize.","triggerScenarios":"Any hub request dispatched through HandlerRegistry.Handle with hctx.Request.Action not present in hr.handlers map — e.g. a newer hub requesting an action added after this agent's version, or a corrupted/out-of-range action integer.","commonSituations":"Hub upgraded ahead of agent (version skew); custom fork adding actions; man-in-the-middle or buggy client sending invalid action codes; stale agent binary that predates the requested feature.","solutions":["Upgrade the beszel agent to match the hub version so all hub actions have handlers.","Check hub/agent version compatibility in the beszel changelog and align both deployments.","If running a fork, register the missing action in hr.handlers or rebuild from matching sources.","Inspect the logged action id and compare against the common action enum to identify which feature is missing."],"exampleFix":"// before\nbeszel-agent v0.9.0 with beszel hub v0.11.0\n// after\nupgrade agent: curl -sL https://beszel.dev/install-agent.sh | bash  # both on same version","handlingStrategy":"try-catch","validationCode":"// hub side: only send actions the agent build supports\nconst knownActions = map[common.ActionType]bool{common.Ping: true, common.CheckFingerprint: true}\nif !knownActions[req.Action] { return fmt.Errorf(\"action %d unsupported by agent\", req.Action) }","typeGuard":null,"tryCatchPattern":"if err := registry.Handle(hctx); err != nil {\n    var unknown *unknownActionError\n    if strings.HasPrefix(err.Error(), \"unknown action\") {\n        slog.Warn(\"agent older than hub; upgrade agent\", \"action\", hctx.Request.Action)\n    }\n    return err\n}","preventionTips":["Keep hub and agent versions in lockstep on every upgrade","Check the beszel changelog for new hub->agent actions before upgrading one side only","Log the numeric action id to identify which feature the stale agent lacks","Test hub/agent pairs in staging after version bumps"],"tags":["websocket","protocol","version-skew","agent"],"backgroundTag":"unknown-request-action","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}