360 lines
10 KiB
Markdown
360 lines
10 KiB
Markdown
# 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](../../frontend/src/components/UptimeWidget.tsx#L3) - Line 3, 53
|
|
- [frontend/src/components/WebSocketStatusCard.tsx](../../frontend/src/components/WebSocketStatusCard.tsx#L2) - Line 2, 87, 94
|
|
- [frontend/src/pages/Dashboard.tsx](../../frontend/src/pages/Dashboard.tsx#L9) - Line 9, 158
|
|
- [frontend/src/pages/SystemSettings.tsx](../../frontend/src/pages/SystemSettings.tsx#L18) - Line 18, 446
|
|
- [frontend/src/pages/Security.tsx](../../frontend/src/pages/Security.tsx#L5) - Line 5, 258, 564
|
|
- [frontend/src/pages/Uptime.tsx](../../frontend/src/pages/Uptime.tsx#L5) - 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](../../frontend/vite.config.ts#L45-L68)) 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:**
|
|
|
|
```bash
|
|
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:**
|
|
|
|
```bash
|
|
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**
|
|
|
|
```bash
|
|
# 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**
|
|
|
|
```bash
|
|
# 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**
|
|
|
|
```bash
|
|
# 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)
|
|
|
|
- [x] Reproduce error in production build
|
|
- [x] Identify all files importing 'Activity'
|
|
- [x] Trace data flow from import to render
|
|
- [x] Identify React version incompatibility
|
|
|
|
### Phase 2: Fix Application (🔄 READY)
|
|
|
|
1. **Execute Option 1 (Update lucide-react):**
|
|
|
|
```bash
|
|
cd /projects/Charon/frontend
|
|
npm install lucide-react@latest
|
|
npm audit fix
|
|
```
|
|
|
|
2. **Build and test:**
|
|
|
|
```bash
|
|
npm run build
|
|
npm run preview
|
|
```
|
|
|
|
3. **If Option 1 fails, execute Option 2 (Downgrade React):**
|
|
|
|
```bash
|
|
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](../../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](../../frontend/vite.config.ts)** - Code splitting config may need adjustment
|
|
- **[frontend/tsconfig.json](../../frontend/tsconfig.json)** - TypeScript target is correct (ES2022)
|
|
- **[.gitignore](../../.gitignore)** - Ensure no production builds committed
|
|
- **[.dockerignore](../../.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:**
|
|
|
|
```bash
|
|
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
|