Fix JWTAuthError: token is expired by 2h30m0s in Gin

This error occurs when a JWT token's expiration claim is past the current server time, or when the token signing key is mismatched between token creation and validation. Fix it by implementing proper token refresh logic, validating the signing method, and returning clear 401 responses with instructions for the client to obtain a new token.

Reading the Stack Trace

Here's what each line means:

• main.JWTAuthMiddleware.func1(0x14000226000) /app/middleware/jwt.go:28 +0x2d8: The JWT middleware at line 28 attempts to parse the token and encounters the expiration validation failure.
• github.com/golang-jwt/jwt/v5.(*Parser).Parse(0x14000118300, {0x14000116420, 0x120}, 0x14000226060): The JWT parser validates the token's claims including the 'exp' field, finding it expired.
• github.com/golang-jwt/jwt/v5.(*Validator).Validate(0x140001a8000, 0x14000196040): The validator checks the expiration timestamp against the current time and returns the expiry error.

Common Causes

func JWTAuthMiddleware(secret string) gin.HandlerFunc {
	return func(c *gin.Context) {
		tokenStr := c.GetHeader("Authorization")
		token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
			return []byte(secret), nil
		})
		if err != nil {
			c.AbortWithStatus(401) // no details, no refresh guidance
			return
		}
		c.Set("user", token.Claims)
		c.Next()
	}
}

token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
	return []byte(secret), nil // does not check t.Method
})

// Auth service uses SECRET_A
// API service uses SECRET_B
token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
	return []byte(os.Getenv("JWT_SECRET")), nil // different env var values
})

The Fix

Validate the Bearer prefix, verify the signing method is HMAC to prevent algorithm switching attacks, distinguish expired tokens from invalid ones, and return structured error responses with guidance on how to refresh the token.

func JWTAuthMiddleware(secret string) gin.HandlerFunc {
	return func(c *gin.Context) {
		tokenStr := c.GetHeader("Authorization")
		token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
			return []byte(secret), nil
		})
		if err != nil {
			c.AbortWithStatus(401)
			return
		}
		c.Set("user", token.Claims)
		c.Next()
	}
}

func JWTAuthMiddleware(secret string) gin.HandlerFunc {
	return func(c *gin.Context) {
		authHeader := c.GetHeader("Authorization")
		if !strings.HasPrefix(authHeader, "Bearer ") {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing bearer token"})
			return
		}
		tokenStr := strings.TrimPrefix(authHeader, "Bearer ")
		token, err := jwt.Parse(tokenStr, func(t *jwt.Token) (interface{}, error) {
			if _, ok := t.Method.(*jwt.SigningMethodHMAC); !ok {
				return nil, fmt.Errorf("unexpected signing method: %v", t.Header["alg"])
			}
			return []byte(secret), nil
		})
		if err != nil {
			if errors.Is(err, jwt.ErrTokenExpired) {
				c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{
					"error": "token_expired",
					"message": "Token has expired. Please refresh your token at /auth/refresh.",
				})
				return
			}
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
			return
		}
		claims, ok := token.Claims.(jwt.MapClaims)
		if !ok {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid claims"})
			return
		}
		c.Set("userID", claims["sub"])
		c.Next()
	}
}

Testing the Fix

package middleware_test

import (
	"net/http"
	"net/http/httptest"
	"testing"
	"time"

	"github.com/gin-gonic/gin"
	"github.com/golang-jwt/jwt/v5"
	"github.com/stretchr/testify/assert"
)

func makeToken(secret string, exp time.Time) string {
	claims := jwt.MapClaims{"sub": "user123", "exp": jwt.NewNumericDate(exp)}
	token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	s, _ := token.SignedString([]byte(secret))
	return s
}

func TestJWT_ValidToken(t *testing.T) {
	gin.SetMode(gin.TestMode)
	r := gin.New()
	r.Use(JWTAuthMiddleware("secret"))
	r.GET("/test", func(c *gin.Context) { c.Status(200) })

	req := httptest.NewRequest(http.MethodGet, "/test", nil)
	req.Header.Set("Authorization", "Bearer "+makeToken("secret", time.Now().Add(time.Hour)))
	w := httptest.NewRecorder()
	r.ServeHTTP(w, req)
	assert.Equal(t, http.StatusOK, w.Code)
}

func TestJWT_ExpiredToken(t *testing.T) {
	gin.SetMode(gin.TestMode)
	r := gin.New()
	r.Use(JWTAuthMiddleware("secret"))
	r.GET("/test", func(c *gin.Context) { c.Status(200) })

	req := httptest.NewRequest(http.MethodGet, "/test", nil)
	req.Header.Set("Authorization", "Bearer "+makeToken("secret", time.Now().Add(-time.Hour)))
	w := httptest.NewRecorder()
	r.ServeHTTP(w, req)
	assert.Equal(t, http.StatusUnauthorized, w.Code)
	assert.Contains(t, w.Body.String(), "token_expired")
}

func TestJWT_MissingHeader(t *testing.T) {
	gin.SetMode(gin.TestMode)
	r := gin.New()
	r.Use(JWTAuthMiddleware("secret"))
	r.GET("/test", func(c *gin.Context) { c.Status(200) })

	req := httptest.NewRequest(http.MethodGet, "/test", nil)
	w := httptest.NewRecorder()
	r.ServeHTTP(w, req)
	assert.Equal(t, http.StatusUnauthorized, w.Code)
}

Run your tests:

go test ./middleware/... -v

Pushing Through CI/CD

git checkout -b fix/gin-jwt-auth-error,git add middleware/jwt.go middleware/jwt_test.go,git commit -m "fix: validate JWT signing method and handle expired tokens gracefully",git push origin fix/gin-jwt-auth-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go mod download
      - run: go vet ./...
      - run: go test ./... -race -coverprofile=coverage.out
      - run: go build ./...

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

go get github.com/bugstack/sdk

import "github.com/bugstack/sdk"

func init() {
  bugstack.Init(os.Getenv("BUGSTACK_API_KEY"))
}

Deploying the Fix (Manual Path)

1. Run go test ./... locally to confirm the JWT middleware works correctly.
2. Open a pull request with the JWT auth changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify the deployment in staging before promoting to production.

Frequently Asked Questions