Fix JWTError: code=401, message=missing or malformed jwt, internal=token contains an invalid number of segments in Echo

This error occurs when Echo's JWT middleware receives a token that is not a valid three-segment JWT string, typically because the Authorization header is missing the Bearer prefix or the token is truncated. Fix it by configuring the JWT middleware with proper token lookup, error handling, and a custom error response.

Reading the Stack Trace

Here's what each line means:

• github.com/labstack/echo-jwt/v4.(*jwtExtractor).extractToken({0x14000226000}): The JWT token extractor cannot find a valid token in the request, or the token string doesn't have the expected three-segment format.
• github.com/labstack/echo-jwt/v4.JWT.func1.1({0x1029e4f80, 0x14000226000}): The Echo JWT middleware processes the request and returns a 401 because token extraction failed.
• github.com/labstack/echo/v4.(*Echo).ServeHTTP(0x14000128680, {0x1029e4f80, 0x140001c40e0}, 0x140002b4000): Echo dispatches the request through the middleware chain where the JWT check occurs.

Common Causes

// Client sends: Authorization: eyJhbGciOi...
// Middleware expects: Authorization: Bearer eyJhbGciOi...

e.Use(echojwt.WithConfig(echojwt.Config{
	SigningKey: []byte(secret),
	// No custom ErrorHandler — returns raw jwt parse errors
}))

// Token stored in cookie "token"
e.Use(echojwt.WithConfig(echojwt.Config{
	SigningKey: []byte(secret),
	// Default TokenLookup is "header:Authorization"
	// Should be "cookie:token"
}))

The Fix

Explicitly configure TokenLookup with the Bearer prefix scheme. Add a custom ErrorHandler that returns a clean JSON error response without leaking internal JWT parsing details to the client.

e.Use(echojwt.WithConfig(echojwt.Config{
	SigningKey: []byte(os.Getenv("JWT_SECRET")),
}))

e.Use(echojwt.WithConfig(echojwt.Config{
	SigningKey:  []byte(os.Getenv("JWT_SECRET")),
	TokenLookup: "header:Authorization:Bearer ",
	ErrorHandler: func(c echo.Context, err error) error {
		return c.JSON(http.StatusUnauthorized, map[string]string{
			"error":   "unauthorized",
			"message": "Invalid or missing authentication token.",
		})
	},
	ContinueOnIgnoredError: false,
}))

Testing the Fix

package main_test

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

	"github.com/golang-jwt/jwt/v5"
	"github.com/labstack/echo/v4"
	"github.com/stretchr/testify/assert"
)

func TestJWT_ValidToken(t *testing.T) {
	e := setupEchoWithJWT("test-secret")
	token := createTestToken("test-secret", time.Now().Add(time.Hour))

	req := httptest.NewRequest(http.MethodGet, "/api/profile", nil)
	req.Header.Set("Authorization", "Bearer "+token)
	rec := httptest.NewRecorder()
	e.ServeHTTP(rec, req)

	assert.Equal(t, http.StatusOK, rec.Code)
}

func TestJWT_MissingToken(t *testing.T) {
	e := setupEchoWithJWT("test-secret")

	req := httptest.NewRequest(http.MethodGet, "/api/profile", nil)
	rec := httptest.NewRecorder()
	e.ServeHTTP(rec, req)

	assert.Equal(t, http.StatusUnauthorized, rec.Code)
	assert.Contains(t, rec.Body.String(), "unauthorized")
}

func TestJWT_MalformedToken(t *testing.T) {
	e := setupEchoWithJWT("test-secret")

	req := httptest.NewRequest(http.MethodGet, "/api/profile", nil)
	req.Header.Set("Authorization", "Bearer not.a.valid.token")
	rec := httptest.NewRecorder()
	e.ServeHTTP(rec, req)

	assert.Equal(t, http.StatusUnauthorized, rec.Code)
}

Run your tests:

go test ./... -v

Pushing Through CI/CD

git checkout -b fix/echo-jwt-error,git add main.go middleware/jwt.go,git commit -m "fix: configure JWT middleware with custom error handler and token lookup",git push origin fix/echo-jwt-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 JWT auth works.
2. Open a pull request with the JWT middleware configuration.
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 authentication in staging.

Frequently Asked Questions