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

## 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

```javascript
// 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

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

### Check Event Flow

```javascript
// 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