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

Regenerate the token on the issuing side (management) and retry

invalid token data: insufficient length

Error message

invalid token data: insufficient length

What it means

UnmarshalToken accepted a non-empty buffer but needs at least 1 + algo.Size() bytes: one byte selecting the AuthAlgo, then that algorithm's fixed signature, then the payload. Shorter data fails here. A frequent root cause is a corrupted or version-mismatched token whose first byte decodes to an algorithm with a signature larger than the remaining data.

Source

Thrown at shared/relay/auth/hmac/v2/token.go:31

	buf := make([]byte, size)

	buf[0] = byte(t.AuthAlgo)
	copy(buf[1:], t.Signature)
	copy(buf[1+len(t.Signature):], t.Payload)

	return buf
}

func UnmarshalToken(data []byte) (*Token, error) {
	if len(data) == 0 {
		return nil, errors.New("invalid token data")
	}

	algo := AuthAlgo(data[0])
	sigSize := algo.Size()
	if len(data) < 1+sigSize {
		return nil, errors.New("invalid token data: insufficient length")
	}

	return &Token{
		AuthAlgo:  algo,
		Signature: data[1 : 1+sigSize],
		Payload:   data[1+sigSize:],
	}, nil
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

Regenerate the token on the issuing side (management) and retry
Verify both ends use the same relay auth package version
Read the full announced frame length before unmarshalling

Defensive patterns

Strategy: validation

Validate before calling

// Minimum structural size: 1 algo byte + smallest supported signature.
if len(data) < 1+AuthAlgounknown.Size() { // use the algo you expect the peer to use
	return fmt.Errorf("relay token frame too short: %d bytes", len(data))
}

Try / catch

token, err := UnmarshalToken(data)
if err != nil {
	if strings.Contains(err.Error(), "insufficient length") {
		// request a fresh token; do not re-parse the same bytes
	}
	return nil, err
}

Prevention

Read complete frames (announced length) before unmarshalling
Keep issuer and validator on the same relay auth package version
Regenerate tokens rather than patching malformed ones

When it happens

Trigger: A truncated token from a partial stream read; a token produced by an incompatible token-format version; random bytes where the algo byte implies a large signature size.

Common situations: Mixed relay auth versions across a self-hosted fleet; frames cut short by transport issues; hand-assembled test buffers sized only for the payload.

Understand the failure class

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

Related errors

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