🛠️ Troubleshooting Guide

This section contains comprehensive troubleshooting documentation for common issues you might encounter in the development environment.

📋 Recent Fixes

• ⚠️ CRITICAL: Anti-Pattern Fix - Relative Imports - Documentation was promoting wrong import patterns (Oct 21, 2025) ⭐ NEW
• public-api.ts → index.ts Migration Complete - Monorepo standardization completed (Oct 21, 2025)
• Linter Errors Fixed - Oct 20, 2025 - @ux-icons import path and SingularityMainComponent template errors

🚨 Critical Issues

System Resource Management

• System Overload Prevention - Comprehensive guide to preventing file descriptor exhaustion, memory leaks, and build process issues ⭐ NEW
• Multi-Monorepo Setup - Complete guide for running 2-3 monorepos simultaneously
• File Descriptor Limits - Fix "EMFILE: too many open files" errors
• MaxListenersExceededWarning - See Multi-Monorepo Setup

NX Cache Corruption

• NX Cache Corruption - Understanding and resolving persistent cache corruption issues
• NX Cache Resolution - Complete resolution guide for NX cache corruption and theme-system integration

Development Server Issues

• Dev Stack Tasks (VS Code, yarn serve, stability) — Canonical guide for dev-serve.js, tasks, ports, auto-restart
• Development Server Improvements - Major improvements made to the development server for immediate startup
• Container Widget Fixes - Dynamic rendering and circular dependency fixes
• Widget Rendering Errors - Final fixes for widget rendering issues

Navigation Issues

• Persistent Navigation Styling - Styling fixes for the persistent navigation system

🔧 Common Solutions

System Resource Monitoring ⭐ NEW

Monitor and prevent system overload issues:

# Monitor system resources and detect issues
yarn monitor:processes

# Emergency cleanup (kills stuck processes)
yarn cleanup:stuck-processes

# Check system health before building
uptime

Cache Management

Most development issues can be resolved with proper cache management:

# Quick cache reset
yarn nx reset

# Complete cache cleanup
rm -rf .nx/cache
rm -rf node_modules/.cache
yarn nx reset

# Nuclear option (if above doesn't work)
rm -rf node_modules
yarn install
yarn nx reset

Build Issues

For build-related problems:

# Safe rebuild without cache
yarn build:safe

# Interactive build manager
yarn unified:build

# Force rebuild everything
yarn build:smart:force

Development Server Issues

If the development server is having problems:

# Check server health
yarn unified:health

# Restart with clean cache
yarn unified:reset
yarn unified:dev

# Check recovery statistics
yarn unified:stats

🧠 Smart Recovery

The system includes intelligent auto-recovery that handles most issues automatically:

• Automatic cache corruption detection and fixing
• 504 timeout error recovery
• Process restart management
• Health monitoring and alerts

📞 Getting Help

If you encounter issues not covered here:

1. Check the logs - Most issues show clear error messages
2. Use the smart recovery system - yarn unified:health and yarn unified:stats
3. Try the nuclear cache cleanup - When all else fails
4. Check the prevention system - Review prevention-system-summary.md for proactive measures

🔄 Prevention

To prevent common issues:

1. Use yarn unified:reset weekly to clear accumulated cache issues
2. Monitor disk space - Large caches can cause problems
3. Keep dependencies updated - Regular updates prevent compatibility issues
4. Use proper shutdown - Always use Ctrl+C instead of force-killing processes

For specific technical details, refer to the individual troubleshooting documents linked above.