igny8/CRITICAL-ISSUE-ROUTER-CONTEXT-ERROR.md

CRITICAL ISSUE: Router Context Error After Git Commits

Date: December 8, 2025
Status: 🔴 CRITICAL - Blocks deployment
Priority: P0 - Must fix before any git push to remote

---

Problem Summary

After committing backend changes to git and syncing with remote, frontend pages break with React Router context errors. The system is currently working but will break when the 6 modified backend files are pushed to remote.

Affected Pages

1. /planner/keywords - Planner Keywords page
2. /writer/tasks - Writer Tasks page
3. /sites - Sites management page
4. /thinker/prompts - Thinker Prompts page
5. /automation - Automation page
6. /setup/add-keywords - Add Keywords setup page

Error Pattern

Primary Error:

Error: useLocation() may be used only in the context of a <Router> component.
    at ModuleNavigationTabs (ModuleNavigationTabs.tsx:22:20)

Secondary Error:

Error: useNavigate() may be used only in the context of a <Router> component.

Associated API Errors (related to permission fixes):

403 Forbidden: /api/v1/auth/sites/5/sectors/
403 Forbidden: /api/v1/auth/sites/
404 Not Found: /api/v1/billing/transactions/balance/

---

Root Cause Analysis

NOT a Code Issue

The code works fine in development and after fresh rebuild. The Router errors are NOT caused by the backend permission fixes.

ACTUAL Cause: Docker Build Cache Invalidation Failure

The Problem Chain:

1. Backend code changes are committed to git
2. Git push triggers remote sync
3. Docker Compose sees changed files
4. Docker does NOT properly rebuild frontend container (uses stale cache)
5. Frontend serves old JavaScript bundles with mismatched module boundaries
6. React Router hooks fail because component tree structure changed
7. Pages crash with "useLocation/useNavigate not in Router context"

Why This Happens:

• Frontend Dockerfile.dev uses npm install (not npm ci)
• package.json changes don't always trigger full rebuild
• Docker layer caching is too aggressive
• node_modules volume persists stale dependencies
• Vite HMR works during dev, but production bundle gets out of sync

---

Current Workaround (Manual Fix)

When errors occur, run these steps:

# 1. Remove ALL containers in Portainer (manual deletion via UI)

# 2. Rebuild infrastructure containers
cd /data/app
docker compose -f docker-compose.yml -p igny8-infra up -d
sleep 3

# 3. Rebuild application containers  
cd /data/app/igny8
docker compose -f docker-compose.app.yml -p igny8-app up -d

# 4. Clear user session
# - Log out from app
# - Clear all cookies
# - Log back in

Result: All pages work again ✅

---

Files That Will Trigger This Issue

Currently modified (unstaged) backend files:

backend/igny8_core/api/base.py          - Superuser bypass in ViewSets
backend/igny8_core/api/permissions.py   - Bypass in permission classes  
backend/igny8_core/api/throttles.py     - Bypass in rate throttling
backend/igny8_core/auth/middleware.py   - Session validation bypass
backend/igny8_core/auth/utils.py        - Account validation bypass
backend/igny8_core/modules/billing/urls.py - Billing endpoint alias

When these are pushed to remote → frontend breaks

---

Permanent Fix Required

Solution A: Fix Docker Build Cache (RECOMMENDED)

1. Update frontend/Dockerfile.dev:

# Before:
RUN npm install

# After:
COPY package.json package-lock.json ./
RUN npm ci --prefer-offline --no-audit
COPY . .

Explanation:

• npm ci does clean install (deletes node_modules first)
• Separate COPY layers ensure package.json changes invalidate cache
• --prefer-offline speeds up rebuild with local cache

2. Update docker-compose.app.yml frontend service:

volumes:
  - ./frontend:/app
  - /app/node_modules  # ← ADD THIS LINE

Explanation:

• Excludes node_modules from volume mount
• Prevents host node_modules from overriding container's
• Forces Docker to use freshly installed dependencies

3. Update deployment commands to use --no-cache flag:

# Development rebuild (when issues occur)
docker compose -f docker-compose.app.yml build --no-cache frontend
docker compose -f docker-compose.app.yml up -d frontend

# Production deployment (always use)
docker compose -f docker-compose.app.yml build --no-cache
docker compose -f docker-compose.app.yml up -d

Solution B: Add Build Verification Step

Add to deployment script:

#!/bin/bash
# deploy_frontend.sh

echo "Building frontend with cache busting..."
docker compose -f docker-compose.app.yml build --no-cache frontend

echo "Checking build artifacts..."
docker run --rm igny8-app-frontend ls -la /app/dist/

echo "Deploying frontend..."
docker compose -f docker-compose.app.yml up -d frontend

echo "Waiting for health check..."
sleep 5
curl -f https://app.igny8.com || echo "WARNING: Frontend not responding"

---

Why Backend Changes Break Frontend

This seems counterintuitive but here's why:

1. Backend changes get committed → triggers rebuild process
2. docker-compose.app.yml rebuilds ALL services (backend + frontend)
3. Backend rebuilds correctly (Django reloads Python modules)
4. Frontend rebuild FAILS SILENTLY (uses cached layers)
5. Old frontend bundle tries to connect to new backend API
6. React component tree structure mismatch → Router context errors

The Fix:

• Ensure frontend ALWAYS rebuilds when ANY file in docker-compose.app.yml changes
• Use --no-cache on deployments
• Add build hash verification

---

Testing Plan

Before Pushing to Remote

1. Test current system works:

curl -I https://app.igny8.com/planner/keywords
curl -I https://app.igny8.com/writer/tasks
curl -I https://app.igny8.com/sites

2. Apply Docker fixes:

• Update frontend/Dockerfile.dev
• Update docker-compose.app.yml
• Test rebuild with --no-cache

3. Verify pages load:

• Login as dev@igny8.com
• Visit all 6 affected pages
• Check browser console for errors

4. Commit and push:

git add backend/
git commit -m "Fix superuser/developer access bypass"
git push origin main

5. Monitor production:

• SSH to server
• Watch docker logs: docker logs -f igny8_frontend
• Check all 6 pages still work

If Errors Still Occur

Run the manual workaround:

1. Remove containers in Portainer
2. Rebuild infra + app
3. Clear cookies + re-login

---

Impact Assessment

Current Status:

• ✅ System working locally
• ✅ All pages functional after rebuild
• ⚠️ 6 backend files uncommitted (permission fixes)
• 🔴 Cannot push to remote (will break production)

Deployment Blocked Until:

• Docker build cache fix implemented
• Frontend Dockerfile.dev updated
• docker-compose.app.yml volume exclusion added
• Deployment script uses --no-cache
• Test push to staging branch first

Business Impact:

• Superuser/developer access fixes are ready but cannot be deployed
• Production system stuck on old code
• Manual rebuild required after every deployment
• High risk of breaking production

---

Next Steps

Immediate (Before Any Git Push):

1. ⏸️ DO NOT commit or push the 6 backend files yet
2. 🔧 Fix frontend/Dockerfile.dev first
3. 🔧 Update docker-compose.app.yml volumes
4. ✅ Test full rebuild with --no-cache
5. ✅ Verify all 6 pages work
6. 📝 Commit Docker fixes first
7. 📝 Then commit backend permission fixes
8. 🚀 Push to remote in correct order

After Router Fix:

1. User will test account/billing pages (user-level)
2. Check for permission leakage in admin menu
3. Verify superuser-only access works correctly
4. Test user menu vs admin menu isolation

---

Related Issues

From Previous Documentation:

• Issue D: Docker Build Cache (FINAL-IMPLEMENTATION-REQUIREMENTS.md)
• Session Contamination (CRITICAL-ISSUE-C.md)
• Subscription Creation Gap (Issue B)

New Findings:

• Router context errors are symptom of build cache issue
• Backend commits trigger the problem (unexpected)
• Frontend needs proper dependency invalidation
• Cookie clearing required after rebuild (session state persists)

---

References

Files Modified (Current Session):

✅ backend/igny8_core/auth/middleware.py - Added superuser bypass
✅ backend/igny8_core/api/permissions.py - Added bypass to 4 classes
✅ backend/igny8_core/api/base.py - Added bypass to ViewSet querysets
✅ backend/igny8_core/auth/utils.py - Added bypass to validation
✅ backend/igny8_core/modules/billing/urls.py - Added endpoint alias
✅ backend/igny8_core/api/throttles.py - Added throttle bypass

Database Changes (Current Session):

✅ Deleted duplicate free-trial plan (ID: 7)
✅ Renamed enterprise → internal (System/Superuser only)
✅ 5 plans now active: free, starter, growth, scale, internal

Documentation Created:

- IMPLEMENTATION-COMPLETE-DEC-8-2025.md (comprehensive summary)
- QUICK-FIX-IMPLEMENTATION-SUMMARY.md (initial fixes)
- SYSTEM-AUDIT-REPORT-2025-12-08.md (audit results)
- CRITICAL-ISSUE-ROUTER-CONTEXT-ERROR.md (this document)

---

Conclusion

The system is working perfectly right now, but will break when code is pushed to remote due to Docker build cache issues.

Priority: Fix Docker caching BEFORE committing the 6 backend permission files.

DO NOT PUSH TO REMOTE until Docker fixes are tested and verified.