Charon/docs/plans/react-activity-icon-error-plan.md

React Runtime Error: "Cannot set properties of undefined (setting 'Activity')" - Root Cause Analysis & Fix Plan

Error Report Date: January 7, 2026 Severity: CRITICAL - Production runtime error blocking application functionality Error Type: TypeError in React production bundle Status: Investigation Complete - Ready for Implementation

---

Error Stack Trace

react.production.js:345 Uncaught TypeError: Cannot set properties of undefined (setting 'Activity')
    at K0 (react.production.js:345:1)
    at Zr (index.js:4:20)
    at tr (use-sync-external-store-shim.production.js:12:13)
    at ar (index.js:4:20)
    at index.js:4:20

---

Root Cause Analysis

1. Primary Issue: React 19.2.3 Compatibility with lucide-react 0.562.0

The error occurs specifically in production builds when lucide-react@0.562.0 icons are imported and used with react@19.2.3. The stack trace reveals the issue originates from:

• use-sync-external-store-shim.production.js - A React 18 compatibility layer used by react-i18next
• react.production.js:345 - React's internal module system trying to set a property on an undefined object

2. Data Flow Trace

1. Import Chain:

   Component (e.g., UptimeWidget.tsx)
     → import { Activity } from 'lucide-react'
     → lucide-react/dist/esm/lucide-react.js
     → lucide-react/dist/esm/icons/activity.js
     → createLucideIcon("activity", iconNode)
   

2. Component Usage Locations:

   • frontend/src/components/UptimeWidget.tsx - Line 3, 53
   • frontend/src/components/WebSocketStatusCard.tsx - Line 2, 87, 94
   • frontend/src/pages/Dashboard.tsx - Line 9, 158
   • frontend/src/pages/SystemSettings.tsx - Line 18, 446
   • frontend/src/pages/Security.tsx - Line 5, 258, 564
   • frontend/src/pages/Uptime.tsx - Line 5, 341

3. Conflict Point:

   • react-i18next@16.5.1 uses use-sync-external-store@1.6.0 as a dependency
   • use-sync-external-store provides a shim for React 18 compatibility
   • React 19 has breaking changes in how it handles module exports and forwardRef
   • lucide-react@0.562.0 was built and tested with React 18, not React 19

3. Why This is Production-Only

• Development mode: React uses unminified code with better error boundaries and more lenient module resolution
• Production mode: Minified React (react.production.js) uses aggressive optimizations that expose the incompatibility
• The Vite build process with code-splitting (vite.config.ts) creates separate chunks for lucide-react icons, which may trigger the module resolution issue

4. Technical Explanation

React 19 introduced changes to:

• Module interop: How React handles CommonJS/ESM exports
• forwardRef behavior: lucide-react uses React.forwardRef extensively
• Component registration: React 19's internal component registry differs from React 18

When lucide-react tries to export the Activity icon using createLucideIcon, React 19's production bundle attempts to set a property on an undefined object in its internal module system, specifically when the icon is being registered or imported.

---

Fix Strategy

Option 1: Update lucide-react (RECOMMENDED)

Status: IMMEDIATE ACTION REQUIRED Risk Level: LOW Impact: High - Fixes root cause

Actions:

1. Upgrade lucide-react to latest version:

   cd frontend
   npm install lucide-react@latest
   

2. Verify compatibility: Check that the new version explicitly supports React 19

   • Expected: lucide-react@0.580+ (hypothetical version with React 19 support)
   • Verify package.json peerDependencies includes React 19

3. Test imports: Run dev build and verify no console errors

Rationale:

• lucide-react@0.562.0 was released BEFORE React 19.2.3 (December 2024)
• Newer versions of lucide-react likely include React 19 compatibility fixes
• This is the cleanest, most maintainable solution

---

Option 2: Downgrade React (FALLBACK)

Status: FALLBACK ONLY Risk Level: MEDIUM Impact: Moderate - Loses React 19 features

Actions:

1. Revert to React 18:

   cd frontend
   npm install react@18.3.1 react-dom@18.3.1
   npm install @types/react@18.3.12 @types/react-dom@18.3.1 --save-dev
   

2. Update all React 19-specific code (if any)

3. Verify Radix UI compatibility (all Radix components need React 18 compat check)

Rationale:

• React 18.3.1 is stable and widely adopted
• All current dependencies (including Radix UI, TanStack Query) support React 18
• Use only if Option 1 fails

---

Option 3: Alternative Icon Library (NUCLEAR OPTION)

Status: LAST RESORT Risk Level: HIGH Impact: Very High - Major refactor

Actions:

1. Replace lucide-react with React Icons or Heroicons
2. Update ALL icon imports across 20+ files
3. Update icon mappings in components

Rationale:

• Only if lucide-react cannot support React 19
• Requires significant development time
• High risk of introducing visual regressions

---

Immediate Testing Strategy

1. Pre-Fix Validation

# Reproduce error in production build
cd frontend
npm run build
npm run preview
# Navigate to Dashboard, check browser console for error

2. Post-Fix Validation

# After applying fix
cd frontend
npm run build
npm run preview

# Open browser to http://localhost:4173
# Test all routes that use Activity icon:
# - /dashboard (UptimeWidget)
# - /uptime
# - /settings/system
# - /security

3. Regression Test Checklist

• All icons render correctly in production build
• No console errors in browser DevTools
• WebSocket status indicators work
• Dashboard uptime widget displays
• Security page loads without errors
• No performance degradation (check bundle size)

4. Automated Tests

# Run frontend unit tests
npm run test

# Run E2E tests
npm run e2e:install
npm run e2e:up:monitor
npm run e2e:test

---

Implementation Steps

Phase 1: Investigation (✅ COMPLETE)

• Reproduce error in production build
• Identify all files importing 'Activity'
• Trace data flow from import to render
• Identify React version incompatibility

Phase 2: Fix Application (🔄 READY)

1. Execute Option 1 (Update lucide-react):

   cd /projects/Charon/frontend
   npm install lucide-react@latest
   npm audit fix
   

2. Build and test:

   npm run build
   npm run preview
   

3. If Option 1 fails, execute Option 2 (Downgrade React):

   npm install react@18.3.1 react-dom@18.3.1
   npm install @types/react@18.3.12 @types/react-dom@18.3.1 --save-dev
   npm run build
   npm run preview
   

Phase 3: Validation

1. Run all automated tests
2. Manually test all routes with Activity icon
3. Check browser console for errors
4. Verify bundle size hasn't increased significantly

Phase 4: Documentation

1. Update CHANGELOG.md with fix details
2. Document React version compatibility requirements
3. Add note to frontend/README.md about React 19 compatibility

---

File Modification Requirements

Files to Modify:

1. frontend/package.json

   • Update lucide-react version (Option 1) OR
   • Downgrade react and react-dom (Option 2)

2. No code changes required if Option 1 succeeds

Configuration Files to Review:

• frontend/vite.config.ts - Code splitting config may need adjustment
• frontend/tsconfig.json - TypeScript target is correct (ES2022)
• .gitignore - Ensure no production builds committed
• .dockerignore - Verify frontend/dist excluded

---

Risk Assessment

Risk	Likelihood	Impact	Mitigation
New lucide-react version breaks other components	LOW	MEDIUM	Comprehensive testing of all icon usages
React downgrade breaks Radix UI	LOW	HIGH	Test all Radix components (Select, Dialog, etc.)
Bundle size increase	LOW	LOW	Monitor with Vite build output
Breaking changes in lucide-react API	VERY LOW	LOW	Icons use stable named exports

---

Rollback Plan

If the fix introduces new issues:

1. Immediate rollback:

   cd frontend
   git checkout HEAD -- package.json package-lock.json
   npm ci
   npm run build
   

2. Deploy previous working version from git history

3. Escalate to Option 2 or Option 3

---

Success Criteria

✅ Fix is successful when:

1. Production build completes without errors
2. All pages render correctly in production preview
3. No console errors related to lucide-react or Activity icon
4. All automated tests pass
5. Manual testing confirms no visual regressions
6. Bundle size remains reasonable (< 10% increase)

---

Additional Notes

Dependencies Analysis:

• React: 19.2.3 (latest)
• lucide-react: 0.562.0 (potentially outdated for React 19)
• react-i18next: 16.5.1 (uses use-sync-external-store@1.6.0)
• All Radix UI components: Compatible with React 19
• TanStack Query: 5.90.16 (Compatible with React 19)

Build Configuration:

• Vite: 7.3.0
• TypeScript: 5.9.3
• Target: ES2022
• Code splitting enabled for icons chunk (may trigger issue)

Browser Compatibility:

• Error observed in: Production build (all browsers)
• Not observed in: Development build

---

Implementation Owner

Assigned To: Implementation Subagent Priority: P0 (Critical - Production Issue) Estimated Time: 30 minutes (Option 1) or 2 hours (Option 2)

---

Related Issues

• Potentially related to React 19 migration
• May affect other components using lucide-react (20+ icons used across codebase)
• Consider audit of all third-party React dependencies for React 19 compatibility

---

Last Updated: January 7, 2026 Next Review: After fix implementation and validation