Diagnosing AdonisJS Auth Failures: Session Driver Misconfiguration

Recognizable Symptoms

When the authentication middleware throws Unauthenticated or Session not found errors after a successful login, the problem usually lies in how the session is stored or retrieved. Common observable symptoms include:

• The login route returns a 401 or redirects back to the login page.
• Browser dev tools show a session cookie that is either missing or has an incorrect domain/path.
• Server logs contain messages such as Session driver not found or Cannot decrypt session data.
• Repeated attempts to login keep failing even though credentials are correct.

Root Cause Table

Cause	Typical Error	Where to Check
Session driver disabled or mis‑named	Session not found	config/session.js
Cache store misconfigured (e.g., Redis host unreachable)	Session persistence failure	config/cache.js, .env
Missing or invalid APP_KEY	Cannot decrypt session data	.env, config/app.js
Middleware order wrong (Auth before Session)	Unauthorized error	start/kernel.js
Session cookie domain/path mismatch	Unauthenticated on subsequent requests	Browser dev tools, config/session.js

Ordered Checks

1. Verify Session Driver Configuration

   cat config/session.js
   // Example snippet
   module.exports = {
     driver: Env.get('SESSION_DRIVER', 'cookie'),
     cookieName: Env.get('SESSION_COOKIE', 'adonisjs_session'),
     // other options
   }
   

   Ensure driver matches a supported value (cookie, redis, database). If you use redis, the driver must be present in config/cache.js as well.

2. Check Environment Variables

   # .env
   SESSION_DRIVER=redis
   SESSION_REDIS_HOST=127.0.0.1
   SESSION_REDIS_PORT=6379
   SESSION_REDIS_PASSWORD=
   APP_KEY=base64:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   

   Run node ace env:dump to confirm values are loaded. Empty or mismatched values will cause failures.

3. Test Cache Store Connectivity

   redis-cli -h $SESSION_REDIS_HOST -p $SESSION_REDIS_PORT ping
   # Expected output: PONG
   

   If you receive ERROR or timeout, correct host/port or credentials.

4. Inspect Middleware Order

   cat start/kernel.js
   // Global middleware stack
   globalMiddleware: [
     'Adonis/Middleware/BodyParser',
     'Adonis/Middleware/Session',
     'Adonis/Middleware/Auth',
   ],
   

   The Session middleware must appear before Auth. If swapped, authentication will never see session data.

5. Validate Cookie Settings

   cat config/session.js
   // Ensure domain and path match your app
   cookie: {
     domain: Env.get('SESSION_COOKIE_DOMAIN', undefined),
     path: Env.get('SESSION_COOKIE_PATH', '/'),
   },
   

   Open the browser console, check the adonisjs_session cookie, and verify its domain/path. A mismatch prevents the cookie from being sent on subsequent requests.

6. Confirm APP_KEY Integrity

   node -e "console.log(process.env.APP_KEY)"
   # Should output a base64 string, e.g., base64:…
   

   Run node ace key:generate if the key is missing or regenerated. Restart the server after changes.

Fixes Tied to Findings

• Driver Mis‑configured – Edit config/session.js to set a valid driver, then restart the dev server.
• Redis Unreachable – Update .env with correct host/port, ensure Redis is running, and restart.
• APP_KEY Problem – Run node ace key:generate, copy the new key into .env, and restart.
• Middleware Order – Move Auth after Session in start/kernel.js.
• Cookie Domain/Path – Align the domain and path settings with your deployment URL; clear old cookies in the browser.

Escalation Criteria

If all checks above pass and authentication still fails, consider:

• Reviewing the exact stack trace in storage/logs/laravel.log or console output for hidden errors.
• Checking for AdonisJS version‑specific changes in config/session.js (e.g., new secure flag).
• Testing with a minimal project scaffold to isolate the issue from custom middleware or route definitions.
• Seeking help in the official AdonisJS Discord or GitHub issues with a reproducible sample.

Always back up configuration files before making changes and reload the environment with a full server restart.