Troubleshooting Nuxt Bearer Auth
Diagnose common Redis, CSRF, endpoint, response mapping, and authorization problems.
Redis Connectivity
Symptom: Authentication operations that create or read a session do not complete as expected.
Check: Confirm the server-side redisUrl points to a running, reachable Redis service and that its connection credentials and TLS scheme match the service configuration. Keep the URL private; it may contain credentials.
Correct: Start or provision the Redis server separately, then set the server-only connection value and retry. The module includes the Redis npm client, but that package does not start a Redis server.
Configuration Values
Symptom: Requests reach an unexpected backend URL or the module cannot connect to the intended API.
Check: Compare the server-side apiBaseUrl and configured endpoint paths with the backend routes. Endpoint values are resolved relative to apiBaseUrl.
Correct: Update the relevant module option in nuxt.config.ts and restart the Nuxt server. See Configuration and Endpoint Configuration.
CSRF Validation
Symptom: A mutating authentication request is rejected by CSRF protection.
Check: Confirm the client obtains the CSRF token from the configured CSRF endpoint and sends it using the configured header name (the default is x-csrf-token). Confirm nuxt-csurf is installed and its configuration is consistent with the module.
Correct: Align the token-fetch flow, header name, and cookie settings with CSRF Configuration. Do not disable CSRF protection as a routine fix.
Backend Endpoint Mismatches
Symptom: Login, registration, refresh, or another operation reaches a backend route that does not handle that operation.
Check: Compare the module's endpoints mapping with the routes implemented by your backend, and confirm the path is relative to the intended API base URL.
Correct: Change the relevant endpoint mapping rather than adding unrelated proxy paths. Keep backend authentication and authorization enabled.
Unexpected Backend Responses
Symptom: The backend responds, but the module does not establish or update the expected session state.
Check: Compare the backend response shape with the configured responsePaths for token, refresh token, user, and success fields. Do not paste real tokens or credentials into logs or support requests.
Correct: Map the actual response fields using Response Paths. The backend must still validate credentials and issue its own tokens.
Authentication vs Authorization
Symptom: A protected operation returns 401 Unauthenticated or 403 Authorization required.
Check: A missing authenticated session causes a 401 from requireAbility; a valid session missing a required ability causes a 403. Authorization is disabled by default and must be enabled/configured before route authorization metadata is enforced.
Correct: Resolve session establishment first. If the user is authenticated, verify the server-derived abilities and authorization configuration. Never use client-supplied ability state to grant access.
Route Guards and Backend Enforcement
Symptom: A page redirect differs from direct API behavior, or a backend request is still denied after a Nuxt route check.
Check: Review the configured public/auth routes and middleware behavior in Route Configuration. Nuxt page guards control navigation; they do not secure direct API calls or replace authorization in your backend.
Correct: Configure the Nuxt route behavior for the UI, protect Nitro handlers where needed, and enforce authentication and authorization on every backend endpoint that handles protected data.