kataras/iris · error

auth: refresh: disabled

Error message

auth: refresh: disabled

What it means

Auth.Refresh was called but refresh-token support is disabled. Refresh is only enabled when the configuration's Keys contain a KIDRefresh entry; otherwise the method refuses to rotate tokens.

Source

Thrown at auth/auth.go:476

func (s *Auth[T]) ExtractAccessToken(ctx *context.Context) string {
	// first try from authorization: bearer header.
	accessToken := s.extractTokenFromHeader(ctx)

	// then if no header, try try extract from cookie.
	if accessToken == "" {
		if cookieName := s.config.Cookie.Name; cookieName != "" {
			accessToken = ctx.GetCookie(cookieName, context.CookieEncoding(s.securecookie))
		}
	}

	return accessToken
}

// Refresh accepts a previously generated refresh token (from SigninHandler) and
// returns a new access and refresh token pair.
func (s *Auth[T]) Refresh(ctx stdContext.Context, refreshToken []byte) ([]byte, []byte, error) {
	if !s.refreshEnabled {
		return nil, nil, fmt.Errorf("auth: refresh: disabled")
	}

	t, _, err := s.verify(ctx, refreshToken)
	if err != nil {
		return nil, nil, fmt.Errorf("auth: refresh: %w", err)
	}

	// refresh the tokens, both refresh & access tokens will be renew to prevent
	// malicious 😈 users that may hold a refresh token.
	accessTok, refreshTok, err := s.sign(t)
	if err != nil {
		return nil, nil, fmt.Errorf("auth: refresh: %w", err)
	}

	return accessTok, refreshTok, nil
}

// RefreshHandler reads the request body which should include data for `RefreshRequest` structure

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Add a KIDRefresh key to the Configuration.Keys map so refresh tokens are enabled
2. Or remove/disable the RefreshHandler route if refresh tokens are not wanted
3. Inform clients that refresh flow is not available in this deployment

Example fix

// before
Keys: map[string]jwt.Key{ "access": accessSecret }
// after
Keys: map[string]jwt.Key{ "access": accessSecret, "refresh": refreshSecret }

// before wiring RefreshHandler, ensure refresh is enabled in this deployment:
if _, ok := cfg.Keys[auth.KIDRefresh]; !ok {
    return fmt.Errorf("RefreshHandler mounted but %s key not configured", auth.KIDRefresh)
}

When it happens

Trigger: Calling Auth.Refresh (via RefreshHandler) when New was constructed with a Keys map lacking the KIDRefresh entry, so s.refreshEnabled is false.

Common situations: An endpoint wired to RefreshHandler but the deployment config never added a refresh key; a client still posting old refresh tokens after refresh support was removed from the server config.

Related errors

• refresh: %w
• auth: refresh: %w
• auth: configuration: %s access token is missing from the con
• refresh max age should be bigger than access token's one[%d
• directoryPath is empty

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/2bf2b99484a7a010. Report an issue: GitHub.