Debugging

Ecosistema completo para organización y gestión de contenido con interfaces espaciales

🐛 Apps Debugging Guide

Comprehensive troubleshooting guide for all applications in the Editor Platform

🚨 Quick Emergency Fixes

Angular 20 Compatibility Issues

App Won't Start After Angular 20 Update

Symptoms:

Build errors with provideProtractorTestingSupport
TypeScript compilation errors with fullTemplateTypeCheck
Nx cache corruption preventing builds

🚀 Immediate Fix Steps:

Clear Nx Cache:

cd /path/to/editor
rm -rf .nx/cache
nx reset
mkdir -p .nx/cache/terminalOutputs
chmod -R 755 .nx

Fix Deprecated Imports:

# Search for deprecated imports
grep -r "provideProtractorTestingSupport" apps/

# Remove provideProtractorTestingSupport from app.config.ts
# Change from:
# import { provideClientHydration, BrowserModule, provideProtractorTestingSupport } from '@angular/platform-browser';
# To:
# import { provideClientHydration, BrowserModule } from '@angular/platform-browser';

Remove Deprecated TypeScript Options:

# Find all tsconfig files with deprecated options
grep -r "fullTemplateTypeCheck" apps/

# Remove fullTemplateTypeCheck from:
# - tsconfig.app.json
# - tsconfig.json  
# - tsconfig.prod.json
# - tsconfig.federation.json

Test the Fix:

nx serve [app-name] --port=[port-number]
# Wait for "Application bundle generation complete"
curl -s http://localhost:[port] | head -10

Prevention: Always check Angular migration guides before upgrading.

📱 App-Specific Debugging

🧪 UX Test App (Port 5300)

Common Issues

Cache Corruption:

# Full recovery
nx reset
rm -rf .nx/cache
mkdir -p .nx/cache/terminalOutputs
nx serve ux-test --port=5300

TypeScript Errors:

# Check for Angular 20 compatibility
grep -r "provideProtractorTestingSupport\|fullTemplateTypeCheck" apps/ux-test/
# Remove any found deprecated imports/options

Port Conflicts:

# Check what's using port 5300
lsof -i :5300
# Kill process if needed
kill -9 [PID]

📝 Editor Web App (Port 5200)

Container Widget Errors

TypeError: Cannot read properties of undefined (reading 'ɵcmp')

Root Causes:

Circular dependency between ContainerWidgetComponent and WidgetHostComponent
Null component registration in services
effect() called outside injection context

Fix Steps:

# 1. Check for circular imports
grep -r "WidgetHostComponent" libs/widgets/src/lib/components/container-widget/

# 2. Verify dynamic rendering architecture
# Ensure ContainerWidgetComponent uses ViewContainerRef + Service pattern

# 3. Fix multiple constructor errors
grep -n "constructor(" libs/widgets/src/lib/components/container-widget/container-widget.component.ts

# 4. Update Sass imports to modern syntax
# Change @import to @use in SCSS files

Unified Navigation Errors

ReferenceError: toggleUnifiedNav is not defined

Fix Steps:

# 1. Check function names in unified nav template
grep -n "toggleUnifiedNav\|toggle3StateNav" servers/scripts/templates/unified-nav.html

# 2. Fix function references to use actual function names
# Use toggle3StateNav instead of toggleUnifiedNav

# 3. Test unified mode
curl -I http://localhost:9100/editor-web

🗺️ Space Map App (Port 5100)

Theme Integration Issues

# Check theme system connection
grep -r "theme-runtime" apps/space-map/
# Verify theme providers in app.config.ts

3D Rendering Problems

# Check WebGL support
# Verify three.js integration
# Test in different browsers

🌌 Singularity App (Port 5400)

Database Connection Issues

# Check database services
ps aux | grep postgres
# Verify connection strings
# Test database connectivity

Logic Builder Errors

# Check canvas rendering
# Verify WebSocket connections
# Test logic execution pipeline

🔧 General Debugging Procedures

Build Errors

# 1. Clear everything
yarn nx reset
rm -rf node_modules dist .nx
yarn install

# 2. Rebuild libraries in order
yarn build:libs

# 3. Build specific app
yarn nx build [app-name] --verbose

# 4. Check for TypeScript errors
npx tsc --noEmit --project apps/[app-name]/tsconfig.json

Runtime Errors

# 1. Check unified server status
ps aux | grep "unified"
yarn unified:status

# 2. Check individual app status
ps aux | grep "nx serve"

# 3. Restart if needed
yarn unified:dev
# or
yarn dev:[app-name]

Port Conflicts

Standard Ports:

ux-test: 5300
editor-web: 5200
space-map: 5100
singularity: 5400
docs-angular: 5010
unified-dev: 9100
unified-production: 9200

# Check port usage
lsof -i :[port-number]

# Kill process using port
kill -9 [PID]

# Start app on different port if needed
nx serve [app-name] --port=[new-port]

Memory Issues

# Check memory usage
ps aux | grep node | awk '{sum+=$6} END {print "Total memory: " sum/1024 " MB"}'

# Increase Node memory limit
export NODE_OPTIONS="--max-old-space-size=8192"

# Use development configuration for lower memory usage
nx serve [app-name] --configuration=development

📊 Health Monitoring

Quick Health Check

# Check all apps status
yarn health:check

# Check specific app
curl -I http://localhost:[port]

# Check unified system
curl -s http://localhost:9100/api/health | jq '.'

Performance Monitoring

# Monitor system resources
yarn health:monitor

# Get performance report
yarn health:report

# Check cache health
yarn health:fix

Recovery Commands

# Quick recovery from cache issues
yarn recover:cache

# Full recovery from corruption
yarn recover:full

# Library-specific recovery
yarn recover:libs

# Smart rebuild based on changes
yarn build:smart

🚨 Emergency Procedures

Complete System Recovery

# 1. Stop all processes
pkill -f "nx serve"
pkill -f "unified"

# 2. Clean everything
rm -rf .nx/cache node_modules dist
yarn install

# 3. Rebuild core dependencies
yarn build:libs

# 4. Test one app at a time
yarn dev:ux-test    # Test on 5300
yarn dev:editor-web # Test on 5200
yarn dev:space-map  # Test on 5100

# 5. Start unified system if individual apps work
yarn unified:dev

Dependency Issues

# Check for dependency conflicts
yarn why [package-name]

# Update specific dependency
yarn upgrade [package-name]

# Rebuild after dependency changes
yarn install --force
yarn build:libs

Environment Issues

# Check Node version
node --version  # Should be 20.x.x

# Check Yarn version
yarn --version

# Check Angular CLI version
npx ng version

# Update if needed
nvm use 20
yarn global add @angular/cli@latest

📝 Error Codes Reference

Common Error Patterns

Error Code	Pattern	Solution
`ENOENT`	Missing cache files	`nx reset && mkdir -p .nx/cache/terminalOutputs`
`ɵcmp`	Component registration error	Check for circular dependencies
`NullInjectorError`	Missing providers	Add providers to app.config.ts
`Cannot find module`	Import path issues	Check tsconfig.json paths
`Port already in use`	Port conflict	Kill process or use different port

Angular 20 Specific Errors

Deprecated Feature	Replacement	Action
`provideProtractorTestingSupport`	None (remove)	Remove import and usage
`fullTemplateTypeCheck`	`strictTemplates`	Remove from angularCompilerOptions
`enableIvy`	Always enabled	Remove from tsconfig

🔍 Debugging Tools

Browser Developer Tools

// Check app registration in unified mode
window.UNIFIED_MODE
window.UNIFIED_CURRENT_APP

// Check theme system
window.themeSystem?.currentTheme
window.themeSystem?.availableThemes

// Monitor performance
console.time('app-load')
// ... app operations
console.timeEnd('app-load')

Network Debugging

# Test app endpoints
curl -I http://localhost:5300/  # ux-test
curl -I http://localhost:5200/  # editor-web
curl -I http://localhost:5100/  # space-map
curl -I http://localhost:9100/  # unified

# Test WebSocket connections
websocat ws://localhost:9100/ws

Log Analysis

# Check application logs
tail -f logs/[app-name].log

# Check unified system logs
tail -f logs/unified-system.log

# Check Nx daemon logs
tail -f .nx/daemon.log

📞 Support Escalation

When to Escalate

Complete system failure after following emergency procedures
Data corruption or loss
Security vulnerabilities discovered
Performance degradation below acceptable thresholds
Unknown error patterns not covered in this guide

Information to Gather

# System information
uname -a
node --version
yarn --version
npx ng version

# Error details
cat .nx/daemon.log | tail -50
ps aux | grep -E "(node|nx|unified)"
lsof -i :5200-5400

# Recent changes
git log --oneline -10
git status

Emergency Contacts

Development Team: Check internal documentation
Infrastructure: System administrators
Security: Security team for vulnerability reports

✅ Verification Checklist

After resolving any issue, verify:

All apps start without errors
All apps accessible on correct ports
Unified system working (if applicable)
No console errors in browser
Theme system functioning
Navigation working correctly
No memory leaks detected
Performance within acceptable ranges

This debugging guide should be the first resource consulted when encountering app issues. Keep it updated as new issues and solutions are discovered.

Last Updated: Current Date
Version: 1.0
Maintainer: Development Team