TROUBLESHOOTING // DIAGNOSTICS PROTOCOL

[ DOCUMENTATION: TROUBLESHOOTING.MD ]
[ STATUS: SUPPORT SYSTEMS ONLINE ]

🚨 COMMON ISSUES

Installation & Setup

Issue: `npm install` fails

Symptoms:

npm ERR! code ERESOLVE
npm ERR! ERESOLVE unable to resolve dependency tree

Solutions:

Clear npm cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Use legacy peer deps:
```
npm install --legacy-peer-deps
```
Update npm:
```
npm install -g npm@latest
```

Check Node version:

node --version  # Should be 18+
nvm install 18  # If using nvm
nvm use 18

Issue: Port 5173 already in use

Symptoms:

Port 5173 is in use, trying another one...

Solutions:

Kill the process (macOS/Linux):
```
lsof -ti:5173 | xargs kill -9
```

Kill the process (Windows):

netstat -ano | findstr :5173
taskkill /PID <PID> /F

Use a different port:
```
npm run dev -- --port 3000
```

Launch & Display

Issue: Blank white screen on launch

Symptoms:

Browser shows blank page
No grid visible
Console may show errors

Solutions:

Check browser console (F12):
- Look for JavaScript errors
- Common errors and fixes below

Clear browser cache:

Chrome: Cmd+Shift+Delete (Mac) or Ctrl+Shift+Delete (Windows)
Firefox: Cmd+Shift+Delete or Ctrl+Shift+Delete
Safari: Cmd+Option+E

Clear localStorage:

// In browser console
localStorage.clear();
location.reload();

Verify build output:
```
npm run build
npm run preview
```
Check for blocking extensions:
- Disable ad blockers
- Disable privacy extensions
- Try incognito/private mode

Issue: Widgets not appearing

Symptoms:

Grid is visible but empty
Specific widgets missing
Dock buttons don't work

Solutions:

Check if widgets are toggled on:
- Click LAUNCHER button
- Verify widget is not disabled
- Try toggling via Dock
Reset layout:
- Open System Core widget
- Settings tab → Factory Reset
- Confirm action
Check console for errors:
- Look for widget-specific errors
- Verify component imports

Verify widget registration:

// In GridContainer.tsx
// Ensure widget is in widgetComponents object

AI Features

Issue: "Please add your Gemini API key"

Symptoms:

AI features (Refine, Expand, etc.) show error
Modal prompts for API key

Solutions:

Add API key via UI:
- Open System Core widget
- Navigate to Settings tab
- Enter API key in input field
- Click Save
Verify API key format:
- Should start with AIzaSy
- Length: ~39 characters
- No spaces or special characters

Test API key:

// In browser console
const apiKey = useAppStore.getState().settings.apiKey;
console.log('API Key:', apiKey ? 'Set' : 'Not set');

Generate new API key:
- Visit https://makersuite.google.com/app/apikey
- Create new project or use existing
- Generate new key
- Copy to Omni-Grid

Issue: AI requests fail or timeout

Symptoms:

Error: Failed to fetch from Gemini API
Error: Request timeout
Error: Invalid response from AI service

Solutions:

Check internet connection:
```
ping google.com
```
Verify API quota:
- Visit Google AI Studio
- Check quota limits
- Free tier: 60 requests/minute

Try different model:

// In widget code, switch from 'pro' to 'flash'
await callGemini(apiKey, prompt, 'flash');

Check for firewall/proxy:
- Corporate networks may block AI APIs
- Try from personal network
- Contact IT for whitelisting
Inspect network request:
- Open DevTools → Network tab
- Filter for generativelanguage.googleapis.com
- Check response status and error message

Layout & Grid

Issue: Widgets overlapping or misaligned

Symptoms:

Widgets stack on top of each other
Layout looks broken
Resize handles missing

Solutions:

Toggle Compact Mode:
- Click AUTOFIT button (top-right)
- Try both ON and OFF states
Unlock layout:
- Ensure UNLOCKED (not LOCKED)
- Try manual repositioning
Reset layout:
- System Core → Settings → Factory Reset

Clear layout cache:

// Browser console
const state = useAppStore.getState();
state.updateLayout([]);
location.reload();

Issue: Cannot drag or resize widgets

Symptoms:

Widgets are static
No drag handles appear
Layout seems frozen

Solutions:

Check layout lock:
- Look for LOCKED button (top-right)
- Click to UNLOCK
Check freeze status:
- Look for FREEZE/RESUME button
- Click RESUME if frozen
Verify browser compatibility:
- Update to latest browser version
- Chrome 90+, Firefox 88+, Safari 14+
Disable browser extensions:
- Some extensions interfere with drag events
- Try incognito mode

Performance

Issue: Slow performance or lag

Symptoms:

UI feels sluggish
Animations stutter
High CPU/memory usage

Solutions:

Reduce active widgets:
- Close unused widgets
- Recommended max: 20 visible
Disable visual effects:
- System Core → Settings
- Turn off Scanlines
- Turn off Matrix Rain
Clear browser cache:
- Old cached files may cause issues

Check browser memory:

// Browser console
console.log(performance.memory);

Close other tabs:
- Free up system resources
Update browser:
- Latest versions have performance improvements

Issue: High memory usage

Symptoms:

// Browser console shows
performance.memory.usedJSHeapSize > 100MB

Solutions:

Export and clear old data:
- Backup current state
- Factory reset
- Re-import only needed data
Limit data in widgets:
- Scratchpad notes: Keep < 50
- Task lists: Keep < 100
- History: Clear periodically
Restart browser:
- Full browser restart (not just tab)

Data & Storage

Issue: Data not persisting

Symptoms:

Settings reset on refresh
Notes disappear
Layout resets

Solutions:

Check localStorage availability:

// Browser console
try {
  localStorage.setItem('test', 'test');
  localStorage.removeItem('test');
  console.log('localStorage: Available');
} catch (e) {
  console.log('localStorage: Blocked', e);
}

Check browser settings:
- Ensure cookies/storage is enabled
- Not in private/incognito mode (some browsers disable storage)

Check storage quota:

// Browser console
navigator.storage.estimate().then(estimate => {
  console.log(`Used: ${estimate.usage} / ${estimate.quota}`);
});

Manual backup:
- Export data immediately after changes
- Don't rely on auto-persistence if failing

Issue: "localStorage quota exceeded"

Symptoms:

QuotaExceededError: Failed to execute 'setItem' on 'Storage'

Solutions:

Clear old backups:
- Export current state
- Factory reset
- Restore only essential data
Reduce data size:
- Delete old notes
- Clear task history
- Remove unused widget data

Check storage usage:

const size = new Blob(Object.values(localStorage)).size;
console.log(`Storage used: ${(size / 1024).toFixed(2)} KB`);

Browser-specific limits:
- Chrome: ~10MB
- Firefox: ~10MB
- Safari: ~5MB (more restrictive)

Backup & Restore

Issue: Backup file won't download

Symptoms:

Click Backup button
No file downloads
No browser prompt

Solutions:

Check browser download settings:
- Ensure downloads are not blocked
- Check for download location permission

Try manual export:

// Browser console
const state = useAppStore.getState();
console.log(JSON.stringify(state, null, 2));
// Copy output and save to file manually

Check popup blocker:
- May be blocking download prompt
- Allow popups for localhost/your domain

Issue: "Invalid backup file" error

Symptoms:

Upload backup file
Error message appears
State not restored

Solutions:

Verify JSON format:
- Open file in text editor
- Should be valid JSON
- Check for corruption

Check backup structure:

{
  "version": 1,
  "timestamp": "2025-...",
  "state": {
    /* AppState */
  }
}

Try older backup:
- If available, use previous backup
- Compare structure with failed file

Manual restore:

// Browser console
const backup = /* paste JSON */;
useAppStore.getState().setGlobalState(backup.state);

Network & External Services

Issue: Weather/Market data not loading

Symptoms:

Widgets show "No data"
External API calls fail

Solutions:

Check internet connection
Verify API endpoints:
- Open DevTools → Network tab
- Look for failed requests
- Check status codes
Check CORS issues:
- Some APIs require proxy
- See Configuration guide for proxy setup
API rate limits:
- Free APIs often have limits
- Wait and retry
- Consider paid tier

🔍 DEBUGGING TECHNIQUES

Enable Verbose Logging

// Add to App.tsx or widget file
useEffect(() => {
  console.log('State changed:', useAppStore.getState());
}, []);

React DevTools

Install browser extension
Open DevTools → Components tab
Inspect component props/state
View component tree

Zustand DevTools

// Add to store.ts
import { devtools } from 'zustand/middleware';

export const useAppStore = create(devtools(persist(/* ... */), { name: 'Omni-Grid' }));

Then open Redux DevTools extension.

Network Debugging

Open DevTools → Network tab
Filter by XHR/Fetch
Inspect request/response
Check timing and status

🆘 GETTING HELP

Self-Help Resources

Read Documentation:
Search GitHub Issues:
- Someone may have reported similar issue
- Check closed issues too
Browser Console:
- F12 or Cmd+Option+I (Mac)
- Check for error messages
- Look for red text/warnings

Reporting Issues

When reporting bugs, include:

System Information:

- OS: macOS 13.0 / Windows 11 / Ubuntu 22.04
- Browser: Chrome 120 / Firefox 121 / Safari 16
- Node: v18.17.0
- npm: v9.8.1
- Omni-Grid: v2.0

Steps to Reproduce:

Launch app
Open X widget
Click Y button
Observe error

Expected vs. Actual:

Expected: Widget should show data
Actual: Shows error message

Console Output:

Paste any error messages from browser console

Screenshots: If visual bug, attach screenshot.

🔧 ADVANCED DIAGNOSTICS

State Dump

// Browser console - dump entire state
console.log(JSON.stringify(useAppStore.getState(), null, 2));

Performance Profiling

// Browser DevTools → Performance tab
// Record → Interact → Stop
// Analyze flame graph

Memory Profiling

// Browser DevTools → Memory tab
// Take heap snapshot
// Compare snapshots to find leaks

📚 FURTHER READING

FAQ - Quick answers
Configuration - Settings guide
Architecture - Technical details

Every bug is a feature request in disguise.

← Back to Documentation Hub

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

TROUBLESHOOTING // DIAGNOSTICS PROTOCOL

🚨 COMMON ISSUES

Installation & Setup

Issue: npm install fails

Issue: Port 5173 already in use

Launch & Display

Issue: Blank white screen on launch

Issue: Widgets not appearing

AI Features

Issue: "Please add your Gemini API key"

Issue: AI requests fail or timeout

Layout & Grid

Issue: Widgets overlapping or misaligned

Issue: Cannot drag or resize widgets

Performance

Issue: Slow performance or lag

Issue: High memory usage

Data & Storage

Issue: Data not persisting

Issue: "localStorage quota exceeded"

Backup & Restore

Issue: Backup file won't download

Issue: "Invalid backup file" error

Network & External Services

Issue: Weather/Market data not loading

🔍 DEBUGGING TECHNIQUES

Enable Verbose Logging

React DevTools

Zustand DevTools

Network Debugging

🆘 GETTING HELP

Self-Help Resources

Reporting Issues

🔧 ADVANCED DIAGNOSTICS

State Dump

Performance Profiling

Memory Profiling

📚 FURTHER READING

Issue: `npm install` fails