micro/go-micro · error

ErrInvalidToken

ErrInvalidToken

Error message

invalid token provided

What it means

ErrInvalidToken (message "invalid token provided") is returned by Provider.Inspect (and helpers such as TokenFromMetadata) in auth/jwt/token when the supplied token string cannot be parsed or verified as a valid JWT. The token may be malformed, tampered with, signed by an unknown key, or expired.

Source

Thrown at auth/jwt/token/token.go:16

package token

import (
	"errors"
	"time"

	"go-micro.dev/v6/auth"
)

var (
	// ErrNotFound is returned when a token cannot be found.
	ErrNotFound = errors.New("token not found")
	// ErrEncodingToken is returned when the service encounters an error during encoding.
	ErrEncodingToken = errors.New("error encoding the token")
	// ErrInvalidToken is returned when the token provided is not valid.
	ErrInvalidToken = errors.New("invalid token provided")
)

// Provider generates and inspects tokens.
type Provider interface {
	Generate(account *auth.Account, opts ...GenerateOption) (*Token, error)
	Inspect(token string) (*auth.Account, error)
	String() string
}

type Token struct {
	// The actual token
	Token string `json:"token"`
	// Time of token creation
	Created time.Time `json:"created"`
	// Time of token expiry
	Expiry time.Time `json:"expiry"`
}

View on GitHub (pinned to 24529f1404)

Solutions

1. Refresh the token via Provider.Generate / auth.Token when it is expired (check Token.Expired()) before re-sending
2. Confirm the client and server share the same signing key/public key and namespace configuration
3. Ensure the Authorization header uses the Bearer scheme and the raw JWT is passed to Inspect intact
4. Re-authenticate to obtain a fresh token if the old one is unrecoverable

Example fix

// before: reusing a possibly expired token blindly
acc, err := provider.Inspect(storedToken.AccessToken)
// after: refresh first when expired
if storedToken.Expired() {
    storedToken, err = provider.Generate(account)
    if err != nil { return err }
}
acc, err := provider.Inspect(storedToken.AccessToken)

// basic pre-checks before sending a token
func tokenUsable(tok *token.Token) bool {
    return tok != nil && tok.AccessToken != "" && !tok.Expired()
}
if !tokenUsable(storedToken) { storedToken = refreshTokenOrReauth() }

func isInvalidToken(err error) bool {
    return errors.Is(err, token.ErrInvalidToken)
}

acc, err := provider.Inspect(rawToken)
if err != nil {
    if errors.Is(err, token.ErrInvalidToken) {
        // trigger re-auth / token refresh flow, return 401 to client
        return reauthenticate()
    }
    return err
}

When it happens

Trigger: Inspect(token) is called with a malformed, empty, wrongly-signed, or expired JWT; TokenFromMetadata extracts the Authorization header value and Inspect rejects it; a client sends a token issued by a different namespace/issuer.

Common situations: Expired access tokens not refreshed before reuse; copying tokens between environments with different signing keys; stripping or renaming the Authorization metadata key so the wrong value is inspected; clock skew between services causing premature expiry.

Understand the failure class

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

Related errors

• ErrInvalidToken
• ErrNotFound
• ErrForbidden
• ErrEncodingToken
• missing authorization token in metadata

AI-assisted analysis of micro/go-micro@24529f1404 (2026-09-01). Data as JSON: /api/errors/3907c1e255b1b978. Report an issue: GitHub.