henrygd/beszel · warning

hub not verified

Error message

hub not verified

What it means

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.

Source

Thrown at agent/handlers.go:72

	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
}

////////////////////////////////////////////////////////////////////////////
////////////////////////////////////////////////////////////////////////////

// GetDataHandler handles system data requests

View on GitHub (pinned to b38fb7dafa)

Solutions

1. Restart both hub and agent so the fingerprint verification handshake runs from scratch.
2. 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.
3. Check hub and agent versions are compatible (fingerprint verification flow changed across releases).
4. Inspect agent logs for earlier verification errors (e.g. fingerprint or SSH errors) that left HubVerified false.

err := handle(hctx)
if err != nil && err.Error() == "hub not verified" {
    log.Warn("request rejected pre-verification; re-running fingerprint handshake")
    if err := verifyFingerprint(); err != nil {
        log.Fatalf("verification failed: %v", err)
    }
}

When it happens

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

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

Related errors

• no matching fingerprints
• fingerprint mismatch
• invalid token
• must set TOKEN or TOKEN_FILE
• invalid signature - check KEY value

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