Skip to content

debug.md

Latest commit

 

History

History
287 lines (207 loc) · 4.68 KB

debug.md

File metadata and controls

287 lines (207 loc) · 4.68 KB

🔍 Web Application Debugging Case Study

Akasa Platform – Authentication & Onboarding Issues (Step-by-Step Debugging)

📌 Overview

This document captures the full debugging process of resolving authentication and onboarding failures in a multi-service web application.
The investigation involved tracing errors across frontend, backend, OAuth configuration, session handling, and proxy layers.

🧱 Architecture Context

🛠️ Debugging Steps

1. Initial Setup

Command

git clone <repo>
cd claw-army
pnpm install
pnpm dev

Result

  • Application started but errors appeared during authentication.

2. PostgreSQL / Docker Issue

Command

docker exec -it claw-army-postgres-1 apt-get update

Error

exec: "apt-get": executable file not found in $PATH

Root Cause

  • Container is Alpine-based (no apt-get)

Fix

  • Skipped manual installation
  • Used existing container setup

3. Database Migration

Command

pnpm --filter @claw/db migrate

Result

[✓] migrations applied successfully!

4. Missing Environment Variable

Error

WEBHOOK_URL_SECRET must be set

Fix

openssl rand -hex 32

Add to .env:

WEBHOOK_URL_SECRET=<generated_value>

5. Backend Connectivity Failure

Error

Could not reach backend

Root Cause

  • UI proxy pointing to wrong port:
    • Expected: 3001
    • Actual backend: 3100

Fix

EXECUTION_SERVICE_URL=http://localhost:3100

6. Google OAuth Error

Error

Error 400: redirect_uri_mismatch

Root Causes

  • Missing PUBLIC_URL
  • Incorrect env variable names

Fix

Add:

PUBLIC_URL=http://localhost:5173

Update auth config:

clientId = process.env.GOOGLE_CLIENT_ID || process.env.AUTH_GOOGLE_ID
clientSecret = process.env.GOOGLE_CLIENT_SECRET || process.env.AUTH_GOOGLE_SECRET

7. Port Conflict

Error

EADDRINUSE: address already in use 3001

Fix

lsof -ti:3001 | xargs -r kill -9

8. Auth Debugging

Commands

curl http://localhost:3001/health
curl http://localhost:3001/auth/get-session

Result

{"status":"ok"}
null

Finding

  • Backend running
  • Session not being created

9. Session Cookie Issue

Symptoms

  • Login success
  • No cookies stored
  • User not authenticated

Root Cause

  • Proxy not forwarding Set-Cookie headers

Fix

  • Extract raw headers
  • Append cookies manually in response

10. Onboarding 500 Error

Error

Internal Server Error

Observations

  • UI receives session
  • Backend does not recognize session
  • API failures breaking page

11. Additional Root Causes

  • Session structure mismatch
  • API routes not resilient
  • Missing host header in auth routes

12. Final Fixes Applied (AI-Assisted Debugging)

  • Fixed port configuration
  • Standardized environment variables
  • Added PUBLIC_URL
  • Implemented cookie forwarding
  • Improved session parsing logic
  • Added error handling for APIs
  • Fixed auth URL construction

13. Verification

Checks

curl -I http://localhost:5173/
curl -I http://localhost:3001/auth/get-session
curl -s http://localhost:5173/onboarding/__data.json

Results

  • OAuth works
  • Cookies stored
  • Onboarding loads successfully

📊 Final Outcome

  • ✅ Authentication working
  • ✅ Session persistence fixed
  • ✅ Backend communication restored
  • ✅ Onboarding flow operational
  • ⚠️ Some features still incomplete (chat, integrations)

🧠 Key Learnings

  • Environment variables must be consistent across services
  • OAuth depends heavily on correct redirect URLs
  • Cookie forwarding is critical in proxy setups
  • Microservice misconfigurations create cascading failures
  • Debugging requires structured step-by-step validation

⚙️ Commands Summary

pnpm install
pnpm dev
pnpm --filter @claw/db migrate
openssl rand -hex 32
lsof -ti:3001 | xargs kill -9
curl http://localhost:3001/health
curl http://localhost:3001/auth/get-session

🚀 Skills Demonstrated

  • Debugging distributed systems
  • API & proxy troubleshooting
  • Authentication flow analysis
  • Session & cookie management
  • Root cause analysis
  • AI-assisted debugging workflow

📌 Status

Core authentication and onboarding issues successfully resolved