🧐[问题 | question or bug?] How to implement refresh token with interceptors

[williamfitzGH]

🧐 问题描述 | Problem description

Originally I would use the response interceptors to intercept the response, detect the 401 and trigger a new request to generate a new access token via refresh and then retry the initial request and respond accordingly.. this way, the original requester will wait on the resp instead of going into the catch (via try/catch).

Issue is, only 2XX status codes are triggering the response interceptor? Therefore, I need to rely on the errorHandler and I am facing weird timing issues whereby the initial request is getting the original 401 response, causing it to except (go into catch), then once that completes it goes back and gets my refresh and my logic that should have fired before the catch is firing after! Very strange behaviour. Looking for support on how to correctly implement this. All original solutions I could locate, all used the response interceptor. I also use to use the response interceptor. So not sure if this is a bug or intended behaviour now with the latest version but I cant for the life of me, figure this out.

💻 示例代码 | Sample code

In my app.tsx:

/**
 * @see https://umijs.org/docs/api/runtime-config#getinitialstate
 * */
export async function getInitialState(): Promise<{
    settings?: Partial<LayoutSettings>;
    currentUser?: API.CurrentUser;
    loading?: boolean;
    fetchUserInfo?: () => Promise<API.CurrentUser | undefined>;
}> {
    let currentUser: API.CurrentUser | undefined;
    let loading = true;

    const fetchUserInfo = async () => {
        try {
            const msg = await getCurrentUser(); // triggers refresh if expired
            return msg.data;
        } catch (_error) {
            // ISSUE HERE, we except before the interception finishes!
            return undefined; // fail silently
        } finally {
            loading = false; // stop loading when done
        }
    };

    const {location} = history;
    if (![loginPath, '/user/register', '/user/register-result'].includes(location.pathname)) {
        currentUser = await fetchUserInfo();
    }

    return {
        fetchUserInfo,
        currentUser,
        loading,
        settings: defaultSettings as Partial<LayoutSettings>,
    };
}

/**
 * @name request configuration, can configure error handling
 * It provides a unified network request and error handling solution based on axios and a hooks' useRequest.
 * @doc https://umijs.org/docs/max/request#configuration
 */
export const request: RequestConfig = {
    baseURL: '/',
    ...errorConfig
};

// errorConfig (don't mind the refresh token in local storage, just for testing purposes!):

import type {RequestOptions} from '@@/plugin-request/request';
import {history, request, RequestConfig} from '@umijs/max';
import {message, notification} from 'antd';
import {refreshAccessToken} from "@/services/user/auth";

// Error handling scheme: error types
enum ErrorShowType {
    SILENT = 0,
    WARN_MESSAGE = 1,
    ERROR_MESSAGE = 2,
    NOTIFICATION = 3,
    REDIRECT = 9,
}

// Response data format agreed with the backend
interface ResponseStructure {
    success: boolean;
    data: any;
    errorCode?: number;
    errorMessage?: string;
    showType?: ErrorShowType;
}

// Track refresh state globally
let isRefreshing = false;
let refreshPromise: Promise<string | null> | null = null;
let pendingQueue: ((token: string | null) => void)[] = [];

// Helper: run queued requests once refresh completes
const processQueue = (token: string | null) => {
    pendingQueue.forEach((cb) => cb(token));
    pendingQueue = [];
};

/**
 * Error handling
 * Built-in error handling of pro, you can make your own changes here
 * @doc https://umijs.org/docs/max/request#configuration
 */
export const errorConfig: RequestConfig = {
    // Error handling: error handling scheme of umi@3.
    errorConfig: {
        // Error thrower
        errorThrower: (res) => {
            const {success, errorMessage} = res as ResponseStructure;

            // Only throw for business errors (success = false), not for HTTP status errors.
            if (!success) {
                const error: any = new Error(errorMessage);
                error.name = 'BizError';
                error.info = res;
                throw error;
            }

            // Let HTTP errors be handled downstream by errorHandler
        },
        //Error receiver and handler
        errorHandler: async (error: any, opts: any) => {
            if (opts?.skipErrorHandler) throw error;
            // Error thrown by our errorThrower.
            if (error.name === 'BizError') {
                const errorInfo: ResponseStructure | undefined = error.info;
                if (errorInfo) {
                    const {errorMessage, errorCode} = errorInfo;
                    switch (errorInfo.showType) {
                        case ErrorShowType.SILENT:
                            // do nothing
                            break;
                        case ErrorShowType.WARN_MESSAGE:
                            void message.warning(errorMessage);
                            break;
                        case ErrorShowType.ERROR_MESSAGE:
                            void message.error(errorMessage);
                            break;
                        case ErrorShowType.NOTIFICATION:
                            notification.open({
                                description: errorMessage,
                                message: errorCode,
                            });
                            break;
                        case ErrorShowType.REDIRECT:
                            // TODO: redirect
                            break;
                        default:
                            void message.error(errorMessage);
                    }
                }
                return;
            }

            // Handle HTTP errors
            if (error.response) {
                const {status, config} = error.response;

                if (status === 401) {
                    // We remove access_token so we do not override our request to refresh token endpoint
                    // (since we use the refresh token in header)
                    localStorage.removeItem('access_token');
                    const refreshToken = localStorage.getItem('refresh_token');
                    if (!refreshToken) {
                        if (history.location.pathname !== '/user/login') {
                            history.push('/user/login');
                        }
                        return Promise.reject(error); // ensure caller sees rejection
                    }

                    // If already refreshing, queue this request
                    if (isRefreshing && refreshPromise) {
                        return new Promise<any>((resolve, reject) => {
                            pendingQueue.push((newToken) => {
                                if (!newToken) {
                                    reject(error); // refresh failed
                                    return;
                                }
                                request(config.url!, {
                                    ...config,
                                    skipErrorHandler: true,
                                })
                                    .then(resolve)
                                    .catch(reject);
                            });
                        });
                    }

                    // First failing request triggers the refresh
                    if (!refreshPromise) {
                        isRefreshing = true;
                        refreshPromise = refreshAccessToken(refreshToken)
                            .then(data => {
                                if (data.access_token) {
                                    localStorage.setItem('access_token', data.access_token);
                                    processQueue(data.access_token);
                                    return data.access_token;
                                } else {
                                    processQueue(null);
                                    localStorage.removeItem('access_token');
                                    localStorage.removeItem('refresh_token');
                                    if (history.location.pathname !== '/user/login') {
                                        history.push('/user/login');
                                    }
                                    return null;
                                }
                            })
                            .catch(() => {
                                processQueue(null);
                                localStorage.removeItem('access_token');
                                localStorage.removeItem('refresh_token');
                                if (history.location.pathname !== '/user/login') {
                                    history.push('/user/login');
                                }
                                return null;
                            })
                            .finally(() => {
                                isRefreshing = false;
                                refreshPromise = null;
                            });
                    }

                    // Wait for the refresh to complete
                    const newToken = await refreshPromise;
                    if (!newToken) return Promise.reject(error);

                    // Retry original request
                    return request(config.url!, {
                        ...config,
                        skipErrorHandler: true,
                    });

                } else if (status === 403) {
                    // Do nothing for 403
                    return;
                }

                // other non-2xx HTTP codes
                return;
            } else if (error.request) {
                // The request was made but no response was received
                // `error.request` is an instance of XMLHttpRequest in the browser and an instance of
                // http.ClientRequest in node.js
                void message.error('No response received! Please retry.');
            } else {
                // Something happened in setting up the request that triggered an Error
                void message.error('Request error, please retry.');
            }
        }
    },

    // Request interceptors
    requestInterceptors: [
        (config: RequestOptions) => {
            // Allow per-request `prefix` override
            // If config.prefix is present (set from API call), use it to rebuild URL
            if (config.prefix) {
                config.url = `${config.prefix}${config.url}`;
                delete config.prefix; // Prevent double prefixing later
            }

            // Always inject latest access token
            const token = localStorage.getItem('access_token');
            if (token) {
                config.headers = {
                    ...config.headers,
                    Authorization: `Bearer ${token}`,
                };
            }

            return config;
        }
    ],

    // Response interceptors
    // Only triggers for 2xx HTTP status codes
    responseInterceptors: [
        (response) => {
            const resData = response.data as ResponseStructure;

            // Handle backend errors
            if (resData?.success === false) {
                void message.error(resData.errorMessage || 'Request failed!');
            }

            return response;
        },
    ],
};

🚑 其他信息 | Other information

OS: Mac OS Sequoia V15.5

Node：v20.19.4

浏览器 | browser：Google Chrome: Version 139.0.7258.139 (Official Build) (arm64)

[dosubot]

Hi @williamfitzGH! I'm Dosu and I’m helping the ant-design-pro team.

This is intended behavior: in Ant Design Pro (and umi@3's request), response interceptors only trigger for 2xx HTTP responses, while non-2xx responses (like 401) are always routed to errorHandler. There is no configuration to change this—refresh token logic and retries must be handled in errorHandler, not in response interceptors. This matches the official design and codebase comments (source).

Your current approach—queuing requests and retrying after refresh in errorHandler—is the recommended pattern. To avoid timing issues, ensure all async logic in errorHandler is carefully managed: queue requests while refreshing, resolve/reject them only after refresh completes, and always await the refresh before retrying the original request. This is the canonical solution for Ant Design Pro as of the latest version (source).

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[williamfitzGH]

@dosu can you provide a working sample then in which we would correctly integrate the refresh pattern inside the errorHandler?

[dosubot]

Here’s a production-ready sample for integrating refresh token logic inside errorHandler in Ant Design Pro (umi@3 request). This pattern is confirmed by community threads and matches your scenario: when a 401 occurs, it queues requests, triggers a single refresh, and retries all pending requests after refresh completes. If refresh fails, it clears tokens and redirects to login. This avoids race conditions and ensures requests only retry after a successful refresh (reference, reference).

// errorConfig.ts
import { history, request, RequestConfig } from '@umijs/max';
import { message, notification } from 'antd';
import { refreshAccessToken } from '@/services/user/auth';

let isRefreshing = false;
let refreshPromise: Promise<string | null> | null = null;
let pendingQueue: ((token: string | null) => void)[] = [];

const processQueue = (token: string | null) => {
  pendingQueue.forEach(cb => cb(token));
  pendingQueue = [];
};

export const errorConfig: RequestConfig = {
  errorConfig: {
    errorHandler: async (error: any, opts: any) => {
      if (opts?.skipErrorHandler) throw error;

      if (error.response) {
        const { status, config } = error.response;

        if (status === 401) {
          localStorage.removeItem('access_token');
          const refreshToken = localStorage.getItem('refresh_token');
          if (!refreshToken) {
            if (history.location.pathname !== '/user/login') {
              history.push('/user/login');
            }
            return Promise.reject(error);
          }

          // Queue requests if refresh in progress
          if (isRefreshing && refreshPromise) {
            return new Promise((resolve, reject) => {
              pendingQueue.push(newToken => {
                if (!newToken) {
                  reject(error);
                  return;
                }
                request(config.url!, {
                  ...config,
                  skipErrorHandler: true,
                })
                  .then(resolve)
                  .catch(reject);
              });
            });
          }

          // Start refresh
          if (!refreshPromise) {
            isRefreshing = true;
            refreshPromise = refreshAccessToken(refreshToken)
              .then(data => {
                if (data.access_token) {
                  localStorage.setItem('access_token', data.access_token);
                  processQueue(data.access_token);
                  return data.access_token;
                } else {
                  processQueue(null);
                  localStorage.removeItem('access_token');
                  localStorage.removeItem('refresh_token');
                  if (history.location.pathname !== '/user/login') {
                    history.push('/user/login');
                  }
                  return null;
                }
              })
              .catch(() => {
                processQueue(null);
                localStorage.removeItem('access_token');
                localStorage.removeItem('refresh_token');
                if (history.location.pathname !== '/user/login') {
                  history.push('/user/login');
                }
                return null;
              })
              .finally(() => {
                isRefreshing = false;
                refreshPromise = null;
              });
          }

          // Wait for refresh to complete
          const newToken = await refreshPromise;
          if (!newToken) return Promise.reject(error);

          // Retry original request
          return request(config.url!, {
            ...config,
            skipErrorHandler: true,
          });
        }
      }
      // ...other error handling (403, network, etc.)
    },
  },
  requestInterceptors: [
    config => {
      const token = localStorage.getItem('access_token');
      if (token) {
        config.headers = {
          ...config.headers,
          Authorization: `Bearer ${token}`,
        };
      }
      return config;
    },
  ],
};

This pattern is robust against multiple simultaneous 401s and avoids infinite loops. Always inject the latest token in request interceptors, not static headers, to prevent stale tokens (reference). If you need more details or want to see community discussions, check issue #11550 and issue #7159.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[williamfitzGH]

@dosu, still having the race conditions.

My errorconfig.ts:

import type {RequestOptions} from '@@/plugin-request/request';
import {history, request, RequestConfig} from '@umijs/max';
import {message} from 'antd';
import {refreshAccessToken} from "@/services/user/auth";

// Error handling scheme: error types
enum ErrorShowType {
    SILENT = 0,
    WARN_MESSAGE = 1,
    ERROR_MESSAGE = 2,
    NOTIFICATION = 3,
    REDIRECT = 9,
}

// Response data format agreed with the backend
interface ResponseStructure {
    success: boolean;
    data: any;
    errorCode?: number;
    errorMessage?: string;
    showType?: ErrorShowType;
}

// Track refresh state globally
let isRefreshing = false;
let refreshPromise: Promise<string | null> | null = null;
let pendingQueue: ((token: string | null) => void)[] = [];

const processQueue = (token: string | null) => {
  pendingQueue.forEach(cb => cb(token));
  pendingQueue = [];
};

/**
 * Error handling
 * Built-in error handling of pro, you can make your own changes here
 * @doc https://umijs.org/docs/max/request#configuration
 */
export const errorConfig: RequestConfig = {
    // Error handling: error handling scheme of umi@3.
    errorConfig: {
        errorHandler: async (error: any, opts: any) => {
            if (opts?.skipErrorHandler) throw error;

            if (error.response) {
                const {status, config} = error.response;

                if (status === 401) {
                    localStorage.removeItem('access_token');
                    const refreshToken = localStorage.getItem('refresh_token');
                    if (!refreshToken) {
                        if (history.location.pathname !== '/user/login') {
                            history.push('/user/login');
                        }
                        return Promise.reject(error);
                    }

                    // Queue requests if refresh in progress
                    if (isRefreshing && refreshPromise) {
                        return new Promise<any>((resolve, reject) => {
                            pendingQueue.push(newToken => {
                                if (!newToken) {
                                    reject(error);
                                    return;
                                }
                                request(config.url!, {
                                    ...config,
                                    skipErrorHandler: true,
                                })
                                    .then(resolve)
                                    .catch(reject);
                            });
                        });
                    }

                    // Start refresh
                    if (!refreshPromise) {
                        isRefreshing = true;
                        refreshPromise = refreshAccessToken(refreshToken)
                            .then(data => {
                                if (data.access_token) {
                                    localStorage.setItem('access_token', data.access_token);
                                    processQueue(data.access_token);
                                    return data.access_token;
                                } else {
                                    processQueue(null);
                                    localStorage.removeItem('access_token');
                                    localStorage.removeItem('refresh_token');
                                    if (history.location.pathname !== '/user/login') {
                                        history.push('/user/login');
                                    }
                                    return null;
                                }
                            })
                            .catch(() => {
                                processQueue(null);
                                localStorage.removeItem('access_token');
                                localStorage.removeItem('refresh_token');
                                if (history.location.pathname !== '/user/login') {
                                    history.push('/user/login');
                                }
                                return null;
                            })
                            .finally(() => {
                                isRefreshing = false;
                                refreshPromise = null;
                            });
                    }

                    // Wait for refresh to complete
                    const newToken = await refreshPromise;
                    if (!newToken) return Promise.reject(error);

                    // Retry original request
                    return request(config.url!, {
                        ...config,
                        skipErrorHandler: true,
                    });
                }
            }
            // ...other error handling (403, network, etc.)
        },
    },

    // Request interceptors
    requestInterceptors: [
        (config: RequestOptions) => {
            // Allow per-request `prefix` override
            // If config.prefix is present (set from API call), use it to rebuild URL
            if (config.prefix) {
                config.url = `${config.prefix}${config.url}`;
                delete config.prefix; // Prevent double prefixing later
            }

            // Always inject latest access token
            const token = localStorage.getItem('access_token');
            if (token) {
                config.headers = {
                    ...config.headers,
                    Authorization: `Bearer ${token}`,
                };
            }

            return config;
        }
    ],

    // Response interceptors
    // Only triggers for 2xx HTTP status codes
    responseInterceptors: [
        (response) => {
            const resData = response.data as ResponseStructure;

            // Handle backend errors
            if (resData?.success === false) {
                void message.error(resData.errorMessage || 'Request failed!');
            }

            return response;
        },
    ],
};

in my app.tsx:

import {PageLoading, SettingDrawer, Settings as LayoutSettings} from '@ant-design/pro-components';
import type {RequestConfig, RunTimeLayoutConfig} from '@umijs/max';
import {history} from '@umijs/max';
import React from 'react';
import {AvatarDropdown, AvatarName, Footer} from '@/components';
import defaultSettings from '../config/defaultSettings';
import {errorConfig} from './requestErrorConfig';
import '@ant-design/v5-patch-for-react-19';
import {getCurrentUser} from "@/services/user/auth";

const isDev =
    process.env.NODE_ENV === 'development' || process.env.CI;
const loginPath = '/user/login';

/**
 * @see https://umijs.org/docs/api/runtime-config#getinitialstate
 * */
export async function getInitialState(): Promise<{
    settings?: Partial<LayoutSettings>;
    currentUser?: API.CurrentUser;
    loading?: boolean;
    fetchUserInfo?: () => Promise<API.CurrentUser | undefined>;
}> {
    let currentUser: API.CurrentUser | undefined;
    let loading = true;

    const fetchUserInfo = async () => {
        try {
            const msg = await getCurrentUser(); // triggers refresh if expired
            return msg.data;
        } catch (_error) {
            return undefined; // fail silently
        } finally {
            loading = false; // stop loading when done
        }
    };

    const {location} = history;
    if (![loginPath, '/user/register', '/user/register-result'].includes(location.pathname)) {
        currentUser = await fetchUserInfo();
    }

    return {
        fetchUserInfo,
        currentUser,
        loading,
        settings: defaultSettings as Partial<LayoutSettings>,
    };
}

// ProLayout supported APIs: https://procomponents.ant.design/components/layout
export const layout: RunTimeLayoutConfig = ({
                                                initialState,
                                                setInitialState,
                                            }) => {
    return {
        // actionsRender: () => [
        //   <Question key="doc" />,
        //   <SelectLang key="SelectLang" />,
        // ],
        avatarProps: {
            src: initialState?.currentUser?.avatar,
            title: <AvatarName/>,
            render: (_, avatarChildren) => {
                return <AvatarDropdown>{avatarChildren}</AvatarDropdown>;
            },
        },
        footerRender: () => <Footer/>,
        onPageChange: () => {
            const {location} = history;
            // Only redirect if loading is complete and user not logged in
            if (!initialState?.loading && !initialState?.currentUser && location.pathname !== loginPath) {
                history.push(loginPath);
            }
        },
        links: [],
        menuHeaderRender: undefined,
        // Custom 403 page
        // unAccessible: <div>unAccessible</div>,
        // Add a loading state
        childrenRender: (children) => {
            if (initialState?.loading) return <PageLoading/>;
            return (
                <>
                    {children}
                    {isDev && (
                        <SettingDrawer
                            disableUrlParams
                            enableDarkTheme
                            settings={initialState?.settings}
                            onSettingChange={(settings) => {
                                setInitialState((preInitialState) => ({
                                    ...preInitialState,
                                    settings,
                                }));
                            }}
                        />
                    )}
                </>
            );
        },
        ...initialState?.settings,
    };
};

/**
 * @name request configuration, can configure error handling
 * It provides a unified network request and error handling solution based on axios and a hooks' useRequest.
 * @doc https://umijs.org/docs/max/request#configuration
 */
export const request: RequestConfig = {
    baseURL: '/',
    ...errorConfig
};

in the fetchUserInfo, it makes the request via getCurrentUser.

export async function getCurrentUser(): Promise<CurrentUserResponse> {
    return request<CurrentUserResponse>(
        "/api/auth/v1/currentUser",
        {
            method: "GET",
            prefix: process.env.REACT_APP_BACK_API_BASE_URL
        }
    );
}

That will return a 401 when access token has expired.. Then the errorHandler triggers, runs all the way down to:

// Wait for refresh to complete
const newToken = await refreshPromise; <---- Once we trigger the await, we instantly go into the catch in fetchUserInfo. Then once that catch runs through, our runtime jumps back in and gets the result from the await (newToken).
if (!newToken) return Promise.reject(error);

// Retry original request
return request(config.url!, {
    ...config,
    skipErrorHandler: true,
});

Once we trigger the await, we instantly go into the catch in fetchUserInfo. Then once that catch runs through, our runtime jumps back in and gets the result from the await (newToken). Not sure if we need to wait for the Ant Design team to comment on this? Essentially the new access token eventually generates and that, but its too late as the user has been redirected back to the login page due to the onpagechange via app.tsx:

onPageChange: () => {
            const {location} = history;
            // Only redirect if loading is complete and user not logged in
            if (!initialState?.loading && !initialState?.currentUser && location.pathname !== loginPath) {
                history.push(loginPath);
            }
        },

[dosubot]

This race condition is a known limitation in Ant Design Pro/umi-request: the async flow in errorHandler doesn't synchronize with getInitialState/fetchUserInfo, so your catch block runs before the refresh and retry logic completes. This means your redirect logic (like onPageChange) can fire too early, before the token is refreshed and the user state is updated source.

There’s no built-in workaround for this in the framework. The best practical solution is to introduce a global or context-based "auth loading" state that blocks redirects while a refresh/retry is in progress. For example, set an authLoading flag when a refresh starts, and only allow redirects (or show login) when both authLoading is false and currentUser is undefined. You can also defer your onPageChange redirect logic until after the refresh/retry completes, or poll/re-invoke fetchUserInfo after a successful refresh source.

Here’s a high-level outline:

// In your errorHandler, set a global authLoading flag
authLoading = true;
const newToken = await refreshPromise;
authLoading = false;

// In onPageChange or wherever you redirect:
if (!authLoading && !initialState?.currentUser && location.pathname !== loginPath) {
  history.push(loginPath);
}

This ensures you only redirect after the refresh/retry logic has finished and user state is up to date. You may need to adapt this to your app’s state management.

Keep an eye on upstream changes in umi-request and Ant Design Pro for future improvements, but for now, manual state management is the most reliable workaround source.

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[williamfitzGH]

I just resolved this myself by using axios and implementing interceptors.response.use.

If a member of the Ant Design team can respond with an actual solution utilising the request from umi, that would be awesome! Otherwise, I will continue using my own solution.