Fix RuntimePanic: runtime error: invalid memory address or nil pointer dereference in middleware in Gin

This panic occurs when a Gin middleware dereferences a nil pointer, typically by accessing a value from the context that was never set or by calling a method on an uninitialized dependency. Fix it by adding nil checks in your middleware, ensuring all dependencies are injected before the server starts, and using Gin's built-in recovery middleware.

Reading the Stack Trace

Here's what each line means:

• main.AuthMiddleware(0x14000226000) /app/middleware/auth.go:18 +0xd8: The AuthMiddleware at line 18 dereferences a nil pointer, likely accessing an uninitialized service or missing context value.
• runtime.gopanic({0x102840ea0, 0x1040b8900}): Go's runtime triggers a panic due to a nil pointer dereference, which will crash the goroutine unless recovered.
• github.com/gin-gonic/gin.RecoveryWithWriter.func1(0x14000226000): Gin's Recovery middleware catches the panic and prevents the server from crashing, but returns a 500 to the client.

Common Causes

var userService *UserService // nil — never assigned

func AuthMiddleware(c *gin.Context) {
	token := c.GetHeader("Authorization")
	user, _ := userService.ValidateToken(token) // panic: nil pointer
	c.Set("user", user)
	c.Next()
}

func RoleMiddleware(c *gin.Context) {
	user := c.MustGet("user").(*User) // panics if "user" key not set
	if user.Role != "admin" {
		c.AbortWithStatus(403)
		return
	}
	c.Next()
}

func AuthMiddleware(c *gin.Context) {
	claims := parseJWT(c.GetHeader("Authorization"))
	c.Set("userID", claims.UserID) // panic if claims is nil
	c.Next()
}

The Fix

Replace the package-level nil variable with a constructor function that takes the dependency as a parameter and validates it at startup. Check the token and error values before using them to prevent nil pointer dereferences at runtime.

var userService *UserService

func AuthMiddleware(c *gin.Context) {
	token := c.GetHeader("Authorization")
	user, _ := userService.ValidateToken(token)
	c.Set("user", user)
	c.Next()
}

func NewAuthMiddleware(svc *UserService) gin.HandlerFunc {
	if svc == nil {
		panic("NewAuthMiddleware: UserService must not be nil")
	}
	return func(c *gin.Context) {
		token := c.GetHeader("Authorization")
		if token == "" {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing authorization header"})
			return
		}
		user, err := svc.ValidateToken(token)
		if err != nil {
			c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "invalid token"})
			return
		}
		c.Set("user", user)
		c.Next()
	}
}

Testing the Fix

package middleware_test

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

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

func TestAuthMiddleware_MissingHeader(t *testing.T) {
	gin.SetMode(gin.TestMode)
	r := gin.New()
	svc := &UserService{}
	r.Use(NewAuthMiddleware(svc))
	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)
}

func TestAuthMiddleware_NilServicePanicsAtInit(t *testing.T) {
	assert.Panics(t, func() {
		NewAuthMiddleware(nil)
	})
}

Run your tests:

go test ./middleware/... -v

Pushing Through CI/CD

git checkout -b fix/gin-middleware-panic,git add middleware/auth.go middleware/auth_test.go,git commit -m "fix: inject UserService into auth middleware to prevent nil panic",git push origin fix/gin-middleware-panic

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 fix passes.
2. Open a pull request with the middleware refactor.
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