OpenNoodl/dev-docs/reference/COMMON-ISSUES.md

Common Issues & Troubleshooting

Solutions to frequently encountered problems when developing OpenNoodl.

Build Issues

"Module not found" Errors

Symptom: Build fails with Cannot find module '@noodl-xxx/...'

Solutions:

1. Run npm install from root directory
2. Check if package exists in packages/
3. Verify tsconfig paths are correct
4. Try: rm -rf node_modules && npm install

"Peer dependency" Warnings

Symptom: npm install shows peer dependency warnings

Solutions:

1. Check if versions are compatible
2. Update the conflicting package
3. Last resort: npm install --legacy-peer-deps
4. Document why in CHANGELOG.md

TypeScript Errors After Update

Symptom: Types that worked before now fail

Solutions:

1. Run npx tsc --noEmit to see all errors
2. Check if @types/* packages need updating
3. Look for breaking changes in updated packages
4. Check tsconfig.json for configuration issues

Webpack Build Hangs

Symptom: Build starts but never completes

Solutions:

1. Check for circular imports: npx madge --circular packages/
2. Increase Node memory: NODE_OPTIONS=--max_old_space_size=4096
3. Check for infinite loops in build scripts
4. Try building individual packages

Runtime Issues

Hot Reload Not Working

Symptom: Changes don't appear without full restart

Solutions:

1. Check webpack dev server is running
2. Verify file is being watched (check webpack config)
3. Clear browser cache
4. Check for syntax errors preventing reload
5. Restart dev server: npm run dev

Node Not Appearing in Picker

Symptom: Created a node but it doesn't show up

Solutions:

1. Verify node is exported in nodelibraryexport.js
2. Check category is valid
3. Verify no JavaScript errors in node definition
4. Restart the editor

"Cannot read property of undefined"

Symptom: Runtime error accessing object properties

Solutions:

1. Add null checks: obj?.property
2. Verify data is loaded before access
3. Check async timing issues
4. Add defensive initialization

State Not Updating

Symptom: Changed input but output doesn't update

Solutions:

1. Verify flagOutputDirty() is called
2. Check if batching is interfering
3. Verify connection exists in graph
4. Check for conditional logic preventing update

React Component Not Receiving Events

Symptom: ProjectModel/NodeLibrary events fire but React components don't update

Solutions:

1. Check if using useEventListener hook (most common issue):

   // ✅ RIGHT - Always use useEventListener
   import { useEventListener } from '@noodl-hooks/useEventListener';
   
   // ❌ WRONG - Direct .on() silently fails in React
   useEffect(() => {
     ProjectModel.instance.on('event', handler, {});
   }, []);
   
   useEventListener(ProjectModel.instance, 'event', handler);
   

2. Check singleton dependency in useEffect:

   // ❌ WRONG - Runs once before instance exists
   useEffect(() => {
     if (!ProjectModel.instance) return;
     ProjectModel.instance.on('event', handler, group);
   }, []); // Empty deps!
   
   // ✅ RIGHT - Re-runs when instance loads
   useEffect(() => {
     if (!ProjectModel.instance) return;
     ProjectModel.instance.on('event', handler, group);
   }, [ProjectModel.instance]); // Include singleton!
   

3. Verify code is loading:

   • Add console.log('🔥 Module loaded') at top of file
   • If log doesn't appear, clear caches (see Webpack issues below)

4. Check event name matches exactly:

   • ProjectModel events: componentRenamed, componentAdded, componentRemoved
   • Case-sensitive, no typos

See also:

• LEARNINGS.md - React + EventDispatcher
• LEARNINGS.md - Singleton Timing

Undo Action Doesn't Execute

Symptom: Action returns success and appears in undo history, but nothing happens

Solutions:

1. Check if using broken pattern:

   // ❌ WRONG - Silent failure due to ptr bug
   const undoGroup = new UndoActionGroup({ label: 'Action' });
   UndoQueue.instance.push(undoGroup);
   undoGroup.push({ do: () => {...}, undo: () => {...} });
   undoGroup.do(); // NEVER EXECUTES
   
   // ✅ RIGHT - Use pushAndDo
   UndoQueue.instance.pushAndDo(
     new UndoActionGroup({
       label: 'Action',
       do: () => {...},
       undo: () => {...}
     })
   );
   

2. Add debug logging:

   do: () => {
     console.log('🔥 ACTION EXECUTING'); // Should print immediately
     // Your action here
   }
   

   If log doesn't print, you have the ptr bug.

3. Search codebase for broken pattern:

   grep -r "undoGroup.push" packages/
   grep -r "undoGroup.do()" packages/
   

   If these appear together, fix them.

See also:

• UNDO-QUEUE-PATTERNS.md - Complete guide
• LEARNINGS.md - UndoActionGroup

Webpack Cache Preventing Code Changes

Symptom: Code changes not appearing despite save/restart

Solutions:

1. Verify code is loading (add module marker):

   // At top of file
   console.log('🔥 MyFile.ts LOADED - Version 2.0');
   

   If this doesn't appear in console, it's a cache issue.

2. Nuclear cache clear (when standard restart fails):

   # Kill processes
   killall node
   killall Electron
   
   # Clear ALL caches
   rm -rf packages/noodl-editor/node_modules/.cache
   rm -rf ~/Library/Application\ Support/Electron
   rm -rf ~/Library/Application\ Support/OpenNoodl  # macOS
   
   # Restart
   npm run dev
   

3. Check build timestamp:

   • Look for 🔥 BUILD TIMESTAMP: in console
   • If timestamp is old, caching is active

4. Verify in Sources tab:

   • Open Chrome DevTools
   • Go to Sources tab
   • Find your file
   • Check if changes are there

See also: LEARNINGS.md - Webpack Caching

Editor Issues

Preview Not Loading

Symptom: Preview panel is blank or shows error

Solutions:

1. Check browser console for errors
2. Verify viewer runtime is built
3. Check for JavaScript errors in project
4. Try creating a new empty project

Property Panel Empty

Symptom: Selected node but no properties shown

Solutions:

1. Verify node has inputs defined
2. Check group values are set
3. Look for errors in property panel code
4. Verify node type is registered

Canvas Performance Issues

Symptom: Node graph is slow/laggy

Solutions:

1. Reduce number of visible nodes
2. Check for expensive render operations
3. Verify no infinite update loops
4. Profile with Chrome DevTools

Git Issues

Merge Conflicts in package-lock.json

Symptom: Complex conflicts in lock file

Solutions:

1. Accept either version
2. Run npm install to regenerate
3. Commit the regenerated lock file

Large File Warnings

Symptom: Git warns about large files

Solutions:

1. Check .gitignore includes build outputs
2. Verify node_modules not committed
3. Use Git LFS for large assets if needed

Testing Issues

Tests Timeout

Symptom: Tests hang or timeout

Solutions:

1. Check for unresolved promises
2. Verify mocks are set up correctly
3. Increase timeout if legitimately slow
4. Check for infinite loops

Snapshot Tests Failing

Symptom: Snapshot doesn't match

Solutions:

1. Review the diff carefully
2. If change is intentional: npm test -- -u
3. If unexpected, investigate component changes

Debugging Tips

Enable Verbose Logging

// Add to see more info
console.log('[DEBUG]', variable);

// For node execution
this.context.debugLog('Message', data);

Use Chrome DevTools

1. Open editor
2. Press Cmd+Option+I (Mac) or Ctrl+Shift+I (Windows)
3. Check Console for errors
4. Use Sources for breakpoints
5. Use Network for API issues

Inspect Node State

// In browser console
const node = NoodlRuntime.instance.getNodeById('node-id');
console.log(node._internal);

Check Event Flow

// Add listener to see all events
model.on('*', (event, data) => {
  console.log('Event:', event, data);
});

Error Messages

"Maximum call stack size exceeded"

Cause: Infinite recursion or circular dependency

Fix:

1. Check for circular imports
2. Add base case to recursive functions
3. Break dependency cycles

"Cannot access before initialization"

Cause: Temporal dead zone with let/const

Fix:

1. Check import order
2. Move declaration before usage
3. Check for circular imports

"Unexpected token"

Cause: Syntax error or wrong file type

Fix:

1. Check file extension matches content
2. Verify JSON is valid
3. Check for missing brackets/quotes

"ENOENT: no such file or directory"

Cause: Missing file or wrong path

Fix:

1. Verify file exists
2. Check path is correct (case-sensitive)
3. Ensure build step completed

Getting Help

1. Search this document first
2. Check existing task documentation
3. Search codebase for similar patterns
4. Check GitHub issues
5. Ask in community channels

Contributing Solutions

Found a solution not listed here? Add it!

1. Edit this file
2. Follow the format: Symptom → Solutions
3. Include specific commands when helpful
4. Submit PR with your addition