What causes "invalid token data" in netbirdio/netbird?

Ensure the client obtains and stores a relay auth token from management before connecting

invalid token data

Error message

invalid token data

What it means

UnmarshalToken rejects a zero-length buffer. The relay HMAC token wire format is at least one algorithm-identifier byte plus a signature, so empty input cannot be a token at all. It usually means the caller passed no token bytes — a client that failed to obtain or attach its management-issued relay auth token.

Source

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

	Signature []byte
	Payload   []byte
}

func (t *Token) Marshal() []byte {
	size := 1 + len(t.Signature) + len(t.Payload)

	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

Ensure the client obtains and stores a relay auth token from management before connecting
Check that the bytes handed to Validate are the complete token frame, not the result of an empty read
Align management, relay, and agent versions so tokens are issued and consumed

Defensive patterns

Strategy: validation

Validate before calling

if len(tokenBytes) == 0 {
	return fmt.Errorf("no relay auth token available; obtain one from management before connecting")
}
if err := validator.Validate(tokenBytes); err != nil {
	return err
}

Try / catch

if err := validator.Validate(data); err != nil {
	if err.Error() == "invalid token data" {
		// deny: the client attached no token; do not retry with the same bytes
	}
	return err
}

Prevention

Treat an empty token as a hard stop, never as a retryable condition
Fetch and persist the relay token immediately after login
Log token length (not contents) when auth fails to distinguish empty from malformed

When it happens

Trigger: Validator.Validate receiving an auth payload of length 0; a relay connection whose first frame carries no token; client code passing a nil slice after a failed token fetch.

Common situations: Token plumbing broken between management and agent; agent older than the relay version that mandates auth; self-hosted relay deployed with auth requirements the client does not fulfill.

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/0c7cc7b9192a4b04. Report an issue: GitHub.