henrygd/beszel · error

unknown action: %d

Error message

unknown action: %d

What it means

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.

Source

Thrown at agent/handlers.go:67

	registry.Register(common.CheckFingerprint, &CheckFingerprintHandler{})
	registry.Register(common.GetContainerLogs, &GetContainerLogsHandler{})
	registry.Register(common.GetContainerInfo, &GetContainerInfoHandler{})
	registry.Register(common.GetSmartData, &GetSmartDataHandler{})
	registry.Register(common.GetSystemdInfo, &GetSystemdInfoHandler{})

	return registry
}

// Register registers a handler for a specific action type
func (hr *HandlerRegistry) Register(action common.WebSocketAction, handler RequestHandler) {
	hr.handlers[action] = handler
}

// Handle routes the request to the appropriate handler
func (hr *HandlerRegistry) Handle(hctx *HandlerContext) error {
	handler, exists := hr.handlers[hctx.Request.Action]
	if !exists {
		return fmt.Errorf("unknown action: %d", hctx.Request.Action)
	}

	// Check verification requirement - default to requiring verification
	if hctx.Request.Action != common.CheckFingerprint && !hctx.HubVerified {
		return errors.New("hub not verified")
	}

	// Log handler execution for debugging
	// slog.Debug("Executing handler", "action", hctx.Request.Action)

	return handler.Handle(hctx)
}

// GetHandler returns the handler for a specific action
func (hr *HandlerRegistry) GetHandler(action common.WebSocketAction) (RequestHandler, bool) {
	handler, exists := hr.handlers[action]
	return handler, exists
}

View on GitHub (pinned to b38fb7dafa)

Solutions

1. Upgrade the beszel agent to match the hub version so all hub actions have handlers.
2. Check hub/agent version compatibility in the beszel changelog and align both deployments.
3. If running a fork, register the missing action in hr.handlers or rebuild from matching sources.
4. Inspect the logged action id and compare against the common action enum to identify which feature is missing.

Example fix

// before
beszel-agent v0.9.0 with beszel hub v0.11.0
// after
upgrade agent: curl -sL https://beszel.dev/install-agent.sh | bash  # both on same version

// hub side: only send actions the agent build supports
const knownActions = map[common.ActionType]bool{common.Ping: true, common.CheckFingerprint: true}
if !knownActions[req.Action] { return fmt.Errorf("action %d unsupported by agent", req.Action) }

if err := registry.Handle(hctx); err != nil {
    var unknown *unknownActionError
    if strings.HasPrefix(err.Error(), "unknown action") {
        slog.Warn("agent older than hub; upgrade agent", "action", hctx.Request.Action)
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• HUB_URL environment variable not set
• invalid signature - check KEY value
• no websocket connection
• ${resp.Error}
• no system data in response

AI-assisted analysis of henrygd/beszel@b38fb7dafa (2026-08-31). Data as JSON: /api/errors/c7ba6e206d7d1273. Report an issue: GitHub.