mastra-ai/mastra · error · HTTPException

Session refresh not configured

Error message

Session refresh not configured

What it means

This HTTP 404 error is thrown by the session-refresh route when the resolved auth provider is absent or does not implement the required ISessionProvider methods (`refreshSession` and `getSessionIdFromRequest`). Session refresh is an opt-in capability of the auth provider.

Source

Thrown at packages/server/src/server/handlers/auth.ts:621

  path: '/auth/refresh',
  responseType: 'datastream-response',
  responseSchema: refreshResponseSchema,
  summary: 'Refresh session',
  description: 'Refreshes the current session, extending its expiry. Sets a new session cookie on success.',
  tags: ['Auth'],
  handler: async ctx => {
    const { mastra, request } = ctx as any;
    const isStudio = isStudioRequest(request);

    try {
      const auth = getAuthProvider(mastra, isStudio);

      if (
        !auth ||
        !implementsInterface<ISessionProvider>(auth, 'refreshSession') ||
        !implementsInterface<ISessionProvider>(auth, 'getSessionIdFromRequest')
      ) {
        throw new HTTPException(404, { message: 'Session refresh not configured' });
      }

      // Get session ID from request
      const sessionId = auth.getSessionIdFromRequest(request);
      if (!sessionId) {
        throw new HTTPException(401, { message: 'No session' });
      }

      // Refresh the session
      const newSession = await auth.refreshSession(sessionId);
      if (!newSession) {
        throw new HTTPException(401, { message: 'Session expired' });
      }

      // Build response with new session headers
      const headers = new Headers({ 'Content-Type': 'application/json' });
      if (implementsInterface<ISessionProvider>(auth, 'getSessionHeaders')) {
        const sessionHeaders = auth.getSessionHeaders(newSession);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use or implement an auth provider that satisfies ISessionProvider (refreshSession + getSessionIdFromRequest).
2. If your provider supports sessions, add the missing refreshSession/getSessionIdFromRequest methods.
3. If refresh isn't needed, remove client calls to the refresh endpoint and rely on normal sign-in lifecycle.

Example fix

// before
class MyAuth { /* no refreshSession */ }
// after
class MyAuth implements ISessionProvider {
  async refreshSession(sessionId: string) { /* ... */ }
  getSessionIdFromRequest(req: Request): string | null { /* ... */ }
}

// only call refresh if the provider supports sessions (check its advertised capabilities)
if (!authProviderCapabilities?.sessionRefresh) {
  return; // skip refresh flow entirely
}

function supportsSessionRefresh(auth: unknown): auth is { refreshSession: Function; getSessionIdFromRequest: Function } {
  return !!auth && typeof (auth as any).refreshSession === 'function'
    && typeof (auth as any).getSessionIdFromRequest === 'function';
}

try {
  const res = await fetch('/api/auth/session/refresh', { method: 'POST', credentials: 'include' });
  if (res.status === 404) throw new Error('Session refresh not supported by this auth provider');
} catch (e) { /* disable silent refresh; use re-login flow */ }

When it happens

Trigger: POST the session refresh endpoint while the auth provider for the request context doesn't implement ISessionProvider — e.g. a basic provider without refreshSession support, or no provider at all.

Common situations: Using a custom/community auth provider that lacks refreshSession; calling refresh routes with credentials-only providers; studio vs non-studio provider misconfiguration.

Related errors

• SSO not configured
• Credentials authentication not configured
• Model "${modelId}" is not available. Available models: ${ids
• ACP connection is not initialized
• Model "${this.options.model}" is not available. Available mo

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/f6ff24df852eabc9. Report an issue: GitHub.