henrygd/beszel · error

invalid token

Error message

invalid token

What it means

createNewSystemForUniversalToken re-validates that the request really carries a universal token bound to a user before creating a new system and fingerprint record. If isUniversalToken is false or userId is empty, it refuses with 'invalid token', defending against non-universal tokens silently spawning systems.

Source

Thrown at internal/hub/agent_connect.go:244

		if fpRecords[i].Fingerprint == agentFingerprint.Fingerprint {
			return fpRecords[i], nil
		}
	}

	// No matching fingerprint record found, but it's
	// an active universal token so create a new system
	if acr.isUniversalToken {
		return acr.createNewSystemForUniversalToken(agentFingerprint)
	}

	return ws.FingerprintRecord{}, errors.New("fingerprint mismatch")
}

// createNewSystemForUniversalToken creates a new system and fingerprint record for a universal token.
func (acr *agentConnectRequest) createNewSystemForUniversalToken(agentFingerprint common.FingerprintResponse) (ws.FingerprintRecord, error) {
	var fpRecord ws.FingerprintRecord
	if !acr.isUniversalToken || acr.userId == "" {
		return fpRecord, errors.New("invalid token")
	}

	fpRecord.Token = acr.token

	systemId, err := acr.createSystem(agentFingerprint)
	if err != nil {
		return fpRecord, err
	}
	fpRecord.SystemId = systemId

	// Set the fingerprint for the new system
	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

View on GitHub (pinned to b38fb7dafa)

Solutions

1. Create the system in the hub UI first and use the generated per-system token
2. If auto-registration is desired, configure the key as a universal token associated with a user
3. Check the hub database/user association for the token (empty userId indicates orphaned token)
4. Re-copy the correct KEY from the intended user's system page

Example fix

// before
KEY=<plain-system-token-on-unknown-system>
// after: add the system in hub UI, then
KEY=<freshly-generated-token>

// verify token kind and ownership before agent start
if !isUniversalToken(os.Getenv("KEY")) && !systemExistsInHub(key) {
    log.Fatal("add the system in the hub first, or use a universal token")
}

rec, err := acr.createNewSystemForUniversalToken(fp)
if err != nil && err.Error() == "invalid token" {
    return errors.New("token must be a universal token tied to a user")
}

When it happens

Trigger: handleNoRecords or handleMultipleRecordsOrUniversalToken delegates to createNewSystemForUniversalToken, but the token lacks the universal flag or the request resolved to an empty userId.

Common situations: Regular (system-specific) token used by an agent whose system entry was deleted; a universal token not properly linked to a user in the hub database; agents connecting to a hub user account mismatch.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• hub not verified
• no matching fingerprints
• must set TOKEN or TOKEN_FILE
• invalid signature - check KEY value
• service name is required

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