{"record":{"id":"f6ff24df852eabc9","repo":"mastra-ai/mastra","slug":"session-refresh-not-configured","errorCode":null,"errorMessage":"Session refresh not configured","messagePattern":"Session refresh not configured","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/auth.ts","lineNumber":621,"sourceCode":"  path: '/auth/refresh',\n  responseType: 'datastream-response',\n  responseSchema: refreshResponseSchema,\n  summary: 'Refresh session',\n  description: 'Refreshes the current session, extending its expiry. Sets a new session cookie on success.',\n  tags: ['Auth'],\n  handler: async ctx => {\n    const { mastra, request } = ctx as any;\n    const isStudio = isStudioRequest(request);\n\n    try {\n      const auth = getAuthProvider(mastra, isStudio);\n\n      if (\n        !auth ||\n        !implementsInterface<ISessionProvider>(auth, 'refreshSession') ||\n        !implementsInterface<ISessionProvider>(auth, 'getSessionIdFromRequest')\n      ) {\n        throw new HTTPException(404, { message: 'Session refresh not configured' });\n      }\n\n      // Get session ID from request\n      const sessionId = auth.getSessionIdFromRequest(request);\n      if (!sessionId) {\n        throw new HTTPException(401, { message: 'No session' });\n      }\n\n      // Refresh the session\n      const newSession = await auth.refreshSession(sessionId);\n      if (!newSession) {\n        throw new HTTPException(401, { message: 'Session expired' });\n      }\n\n      // Build response with new session headers\n      const headers = new Headers({ 'Content-Type': 'application/json' });\n      if (implementsInterface<ISessionProvider>(auth, 'getSessionHeaders')) {\n        const sessionHeaders = auth.getSessionHeaders(newSession);","sourceCodeStart":603,"sourceCodeEnd":639,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/auth.ts#L603-L639","documentation":"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.","triggerScenarios":"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.","commonSituations":"Using a custom/community auth provider that lacks refreshSession; calling refresh routes with credentials-only providers; studio vs non-studio provider misconfiguration.","solutions":["Use or implement an auth provider that satisfies ISessionProvider (refreshSession + getSessionIdFromRequest).","If your provider supports sessions, add the missing refreshSession/getSessionIdFromRequest methods.","If refresh isn't needed, remove client calls to the refresh endpoint and rely on normal sign-in lifecycle."],"exampleFix":"// before\nclass MyAuth { /* no refreshSession */ }\n// after\nclass MyAuth implements ISessionProvider {\n  async refreshSession(sessionId: string) { /* ... */ }\n  getSessionIdFromRequest(req: Request): string | null { /* ... */ }\n}","handlingStrategy":"validation","validationCode":"// only call refresh if the provider supports sessions (check its advertised capabilities)\nif (!authProviderCapabilities?.sessionRefresh) {\n  return; // skip refresh flow entirely\n}","typeGuard":"function supportsSessionRefresh(auth: unknown): auth is { refreshSession: Function; getSessionIdFromRequest: Function } {\n  return !!auth && typeof (auth as any).refreshSession === 'function'\n    && typeof (auth as any).getSessionIdFromRequest === 'function';\n}","tryCatchPattern":"try {\n  const res = await fetch('/api/auth/session/refresh', { method: 'POST', credentials: 'include' });\n  if (res.status === 404) throw new Error('Session refresh not supported by this auth provider');\n} catch (e) { /* disable silent refresh; use re-login flow */ }","preventionTips":["Verify your auth provider implements ISessionProvider before wiring refresh calls.","Gate refresh logic behind a capabilities flag from server config.","Test auth flows against both studio and non-studio contexts."],"tags":["http-404","session","auth-configuration"],"backgroundTag":"auth-provider-not-configured","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}