What causes "invalid payload: insufficient length" in netbirdio/netbird?

Create tokens only with the MarshalToken from the same package version as the validator

invalid payload: insufficient length

Error message

invalid payload: insufficient length

What it means

Validator.Validate requires the token payload to be at least minLengthUnixTimestamp bytes, because the payload is a decimal Unix timestamp that the validator later parses and expiry-checks. The token decoded structurally but its payload is too short to hold that timestamp, so it was not produced by the matching Marshal counterpart or was truncated after the signature.

Source

Thrown at shared/relay/auth/hmac/v2/validator.go:33

}

func NewValidator(secret []byte) *Validator {
	return &Validator{secret: secret}
}

func (v *Validator) Validate(data any) error {
	d, ok := data.([]byte)
	if !ok {
		return fmt.Errorf("invalid data type")
	}

	token, err := UnmarshalToken(d)
	if err != nil {
		return fmt.Errorf("unmarshal token: %w", err)
	}

	if len(token.Payload) < minLengthUnixTimestamp {
		return errors.New("invalid payload: insufficient length")
	}

	hashFunc := token.AuthAlgo.New()
	if hashFunc == nil {
		return fmt.Errorf("unsupported auth algorithm: %s", token.AuthAlgo)
	}

	h := hmac.New(hashFunc, v.secret)
	h.Write(token.Payload)
	expectedMAC := h.Sum(nil)

	if !hmac.Equal(token.Signature, expectedMAC) {
		return errors.New("invalid signature")
	}

	timestamp, err := strconv.ParseInt(string(token.Payload), 10, 64)
	if err != nil {
		return fmt.Errorf("invalid payload: %w", err)

View on GitHub (pinned to 93e97f4bf1)

Solutions

Create tokens only with the MarshalToken from the same package version as the validator
Reissue the token from management
Verify relay and management run the same auth version

Defensive patterns

Strategy: try-catch

Try / catch

if err := validator.Validate(data); err != nil {
	if strings.Contains(err.Error(), "invalid payload: insufficient length") {
		// token not minted by a compatible MarshalToken; reissue it
	}
	return err
}

Prevention

Only mint tokens with MarshalToken from the same version as the validator
Never hand-assemble token payloads
Version-pin management and relay when token formats change

When it happens

Trigger: Hand-crafted or version-skewed tokens whose payload omits the timestamp; a frame truncated exactly after the signature bytes.

Common situations: Integrations building tokens manually instead of using MarshalToken; management and relay running different auth versions; malformed fixtures in tests.

Related errors

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/68a35b0d482682a5. Report an issue: GitHub.