henrygd/beszel · error

no matching fingerprints

Error message

no matching fingerprints

What it means

handleNoRecords fires when the hub finds no fingerprint records associated with the presented token. A new system is auto-created only if the token is a valid universal token tied to a user; otherwise the connection is rejected. This prevents unknown tokens from registering systems.

Source

Thrown at internal/hub/agent_connect.go:194

		return acr.handleNoRecords(agentFingerprint)
	}

	// Single record - handle as regular token
	if len(fpRecords) == 1 && !acr.isUniversalToken {
		return acr.handleSingleRecord(fpRecords[0], agentFingerprint)
	}

	// Multiple records or universal token - look for matching fingerprint
	return acr.handleMultipleRecordsOrUniversalToken(fpRecords, agentFingerprint)
}

// handleNoRecords handles the case where no fingerprint records are found for a token.
// A new system is created if the token is a valid universal token.
func (acr *agentConnectRequest) handleNoRecords(agentFingerprint common.FingerprintResponse) (ws.FingerprintRecord, error) {
	var fpRecord ws.FingerprintRecord

	if !acr.isUniversalToken || acr.userId == "" {
		return fpRecord, errors.New("no matching fingerprints")
	}

	return acr.createNewSystemForUniversalToken(agentFingerprint)
}

// handleSingleRecord handles the case with a single fingerprint record. It validates
// the agent's fingerprint against the stored one, or sets it on first connect.
func (acr *agentConnectRequest) handleSingleRecord(fpRecord ws.FingerprintRecord, agentFingerprint common.FingerprintResponse) (ws.FingerprintRecord, error) {
	// If no current fingerprint, update with new fingerprint (first time connecting)
	if fpRecord.Fingerprint == "" {
		if err := acr.hub.SetFingerprint(&fpRecord, agentFingerprint.Fingerprint); err != nil {
			return fpRecord, err
		}
		// Update the record with the fingerprint that was set
		fpRecord.Fingerprint = agentFingerprint.Fingerprint
		return fpRecord, nil
	}

View on GitHub (pinned to b38fb7dafa)

Solutions

1. Verify the agent's KEY matches a token defined in the hub for the target user
2. Re-add the system in the hub and update the agent's KEY to the freshly generated token
3. If using a universal token, confirm it's configured as such and associated with a user (not empty userId)
4. Confirm the agent is connecting to the correct hub URL

Example fix

// before
KEY=<old-key-from-deleted-system>
// after: regenerate in hub UI → Add System, then
KEY=<new-token> ./beszel-agent

// preflight: confirm the token exists in the hub for this user
systems := hub.ListSystems(token)
if len(systems) == 0 && !isUniversalToken(token) {
    log.Fatal("token unknown to hub; re-add the system and copy the new KEY")
}

rec, err := acr.handleNoRecords(fp)
if err != nil && err.Error() == "no matching fingerprints" {
    // re-register: add system in hub UI, restart agent with new KEY
    return retryWithNewKey()
}

When it happens

Trigger: An agent presents a token that has no fingerprint records in the database and the token is not flagged universal (or the resolved userId is empty).

Common situations: System was deleted in the hub while the agent still holds the old key; agent pointed at the wrong hub whose database has no such token; token copied from a different user's account; multi-user setup where the token wasn't issued as a universal key.

Related errors

• must set TOKEN or TOKEN_FILE
• hub not verified
• fingerprint mismatch
• invalid token
• invalid signature - check KEY value

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