academic_project_tracker

🔧 Troubleshooting Guide

Solutions to common issues with Research Project Tracker.

---

Quick Fixes

App Won’t Start

Try these in order:

1. Check Node.js version

   node --version  # Should be v16.0.0 or higher
   

2. Reinstall dependencies

   rm -rf node_modules package-lock.json
   npm install
   cd src/frontend
   rm -rf node_modules package-lock.json
   npm install
   cd ../..
   

3. Check ports

   # Kill processes on ports 5050 and 5173
   lsof -ti:5050 | xargs kill -9
   lsof -ti:5173 | xargs kill -9
   

4. Restart

   npm run dev
   

---

Installation Issues

“npm: command not found”

Problem: Node.js/npm not installed

Solution:

# macOS
brew install node

# Windows
# Download from https://nodejs.org/

# Linux (Ubuntu/Debian)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

“Permission denied” on npm install

Problem: Insufficient permissions

Solution:

# Option 1: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Option 2: Use npx
npx npm install

# Option 3: Use sudo (not recommended)
sudo npm install

Dependencies fail to install

Problem: Network issues or corrupted cache

Solution:

# Clear npm cache
npm cache clean --force

# Delete lock file and node_modules
rm -rf node_modules package-lock.json
rm -rf src/frontend/node_modules src/frontend/package-lock.json

# Reinstall
npm install
cd src/frontend && npm install && cd ../..

“Cannot find module” errors

Problem: Missing dependencies

Solution:

# Install missing backend dependencies
npm install

# Install missing frontend dependencies
cd src/frontend
npm install
cd ../..

# If specific module is missing
npm install <module-name>

---

Startup Issues

Port 5050 already in use

Problem: Backend port occupied

Solution:

# macOS/Linux
lsof -ti:5050 | xargs kill -9

# Windows (PowerShell)
netstat -ano | findstr :5050
taskkill /PID <process_id> /F

# Or change port in .env
echo "PORT=5051" > .env

Port 5173 already in use

Problem: Frontend port occupied

Solution:

# macOS/Linux
lsof -ti:5173 | xargs kill -9

# Windows (PowerShell)
netstat -ano | findstr :5173
taskkill /PID <process_id> /F

# Or edit src/frontend/vite.config.js
# Change port in server.port setting

“EADDRINUSE” error

Problem: Port conflict

Solution:

# Find and kill process
npx kill-port 5050 5173

# Or restart computer (nuclear option)

Backend starts but frontend doesn’t

Problem: Frontend dependencies or build issue

Solution:

# Rebuild frontend
cd src/frontend
rm -rf node_modules dist .vite
npm install
npm run dev

Frontend starts but can’t connect to backend

Problem: Backend not running or wrong URL

Solution:

1. Verify backend is running:

   curl http://localhost:5050/api/health
   # Should return: {"status":"ok"}
   

2. Check frontend API URL in src/frontend/src/config.js:

   export const API_URL = 'http://localhost:5050/api'
   

3. Check browser console (F12) for errors

---

Database Issues

“Database is locked”

Problem: Multiple processes accessing database

Solution:

# Stop all instances
pkill -f "node.*backend"

# Remove lock file (if exists)
rm src/backend/data/tracker.db-lock

# Restart
npm run dev

Database file not found

Problem: Database not created or wrong path

Solution:

# Check if database exists
ls -l src/backend/data/tracker.db

# If not, app will create it automatically on first start
npm run dev

# Or specify path in .env
echo "DATABASE_PATH=src/backend/data/tracker.db" > .env

Corrupted database

Problem: Database file is damaged

Solution:

# Check integrity
sqlite3 src/backend/data/tracker.db "PRAGMA integrity_check;"

# If corrupted, restore from backup
cp backups/tracker-latest.db src/backend/data/tracker.db

# If no backup, try to recover
sqlite3 src/backend/data/tracker.db ".recover" > recovered.sql
# Then create new database and import

“SQLITE_ERROR: no such table”

Problem: Database schema not initialized

Solution:

# Delete database and let app recreate it
rm src/backend/data/tracker.db

# Restart app (will run migrations)
npm run dev

# Or run migrations manually
npm run migrate

Can’t write to database

Problem: File permissions

Solution:

# Fix permissions
chmod 644 src/backend/data/tracker.db
chmod 755 src/backend/data

# Check ownership
ls -l src/backend/data/tracker.db

# Fix ownership if needed
chown $USER:$USER src/backend/data/tracker.db

---

Frontend Issues

Blank white screen

Problem: JavaScript error or build issue

Solution:

1. Open browser console (F12) and check for errors
2. Clear browser cache (Ctrl+Shift+Delete)
3. Rebuild frontend:

   cd src/frontend
   rm -rf dist node_modules
   npm install
   npm run build
   npm run dev
   

“Failed to fetch” errors

Problem: Can’t connect to backend API

Solution:

1. Check backend is running at http://localhost:5050/api/health
2. Check CORS settings in src/backend/server.js
3. Verify API_URL in frontend config
4. Check browser console for specific error

Tasks not saving

Problem: API call failing or database issue

Solution:

1. Open browser console (F12) and check Network tab
2. Verify backend is running
3. Check database write permissions
4. Look for error messages in backend logs

Drag and drop not working

Problem: Browser compatibility or JavaScript error

Solution:

1. Update browser to latest version
2. Try different browser (Chrome, Firefox, Safari)
3. Check console for JavaScript errors
4. Clear cache and reload

Tags not displaying colors

Problem: CSS not loading or color format issue

Solution:

1. Hard refresh (Ctrl+Shift+R or Cmd+Shift+R)
2. Check if Tailwind CSS is loaded (inspect element)
3. Rebuild frontend
4. Verify tag colors are in correct format (hex: #FF0000)

---

Browser Issues

Recommended Browsers

• Chrome/Chromium: v90+
• Firefox: v88+
• Safari: v14+
• Edge: v90+

Clear Browser Data

Chrome/Edge:

1. Press Ctrl+Shift+Delete (Cmd+Shift+Delete on Mac)
2. Select “Cached images and files”
3. Click “Clear data”
4. Reload page (F5)

Firefox:

1. Press Ctrl+Shift+Delete
2. Select “Cache”
3. Click “Clear Now”
4. Reload page

Safari:

1. Safari → Preferences → Advanced
2. Enable “Show Develop menu”
3. Develop → Empty Caches
4. Reload page

Disable Browser Extensions

Some extensions interfere with the app:

1. Open browser in incognito/private mode
2. Test if app works
3. If yes, disable extensions one by one to find culprit

---

Performance Issues

App is slow

Problem: Large database or browser performance

Solution:

1. Clean up old data:

   # Archive completed tasks
   # Delete old whiteboard notes
   # Remove archived projects
   

2. Check database size:

   du -h src/backend/data/tracker.db
   # If >50MB, consider cleanup
   

3. Optimize database:

   sqlite3 src/backend/data/tracker.db "VACUUM;"
   

4. Close other browser tabs

5. Restart browser

Long load times

Problem: Large dataset or slow query

Solution:

1. Check browser Network tab for slow requests
2. Add indexes to database (advanced):

   CREATE INDEX idx_tasks_project ON tasks(project_id);
   CREATE INDEX idx_tasks_status ON tasks(status);
   

3. Reduce number of visible tasks (use filters)

Memory usage high

Problem: Memory leak or too many components

Solution:

1. Restart browser
2. Close unused tabs
3. Clear browser cache
4. Update browser to latest version

---

Data Issues

Missing tasks or projects

Problem: Deleted by accident or sync issue

Solution:

1. Check “Archived” items (might be hidden)
2. Search for the item (might be filtered)
3. Restore from backup:

   cp backups/tracker-latest.db /tmp/test.db
   # Compare databases to find missing data
   

Duplicate tasks appearing

Problem: Sync conflict or import issue

Solution:

# Remove duplicates (SQL)
sqlite3 src/backend/data/tracker.db
DELETE FROM tasks WHERE id NOT IN (
    SELECT MIN(id) FROM tasks GROUP BY title, project_id
);
.quit

Tags disappeared

Problem: Database issue or accidental deletion

Solution:

1. Check if tags still exist but aren’t showing
2. Restore from backup
3. Recreate tags (colors and names)

Links not working

Problem: URL format or copy-paste issue

Solution:

1. Ensure URL includes http:// or https://
2. Use full URLs, not shortened links
3. Test link in separate browser tab

---

Network Issues

“Failed to load resource” errors

Problem: Local server not responding

Solution:

1. Verify both backend and frontend are running
2. Check firewall isn’t blocking ports 5050/5173
3. Try accessing http://localhost:5050/api/health directly

CORS errors

Problem: Cross-origin request blocked

Solution: Edit src/backend/server.js to ensure CORS is enabled:

const cors = require('cors');
app.use(cors({
  origin: 'http://localhost:5173',
  credentials: true
}));

API timeout errors

Problem: Request taking too long

Solution:

1. Check database size and optimize
2. Increase timeout in frontend API calls
3. Check for long-running queries in backend logs

---

Platform-Specific Issues

macOS

“App is damaged” warning:

xattr -cr /path/to/project_tracker

SQLite not found:

brew install sqlite

Port permission errors:

# Use ports above 1024 (5050, 5173 are fine)
# Or run with sudo (not recommended)

Windows

PowerShell script execution disabled:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Path too long errors:

• Move project closer to C:\ (e.g., C:\projects\tracker)

npm scripts not working:

• Use Git Bash instead of CMD or PowerShell
• Or install WSL2 and run in Linux environment

Linux

Permission errors:

# Fix ownership
sudo chown -R $USER:$USER .

# Fix permissions
chmod -R 755 .

Missing dependencies:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential sqlite3

# Fedora/RHEL
sudo dnf install -y gcc-c++ sqlite

SELinux issues:

# Temporarily disable
sudo setenforce 0

# Or configure SELinux policy

---

Development Issues

Hot reload not working

Problem: File watcher not detecting changes

Solution:

# Increase file watcher limit (Linux)
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Restart dev server
npm run dev

Build fails

Problem: Compilation errors or missing dependencies

Solution:

# Clean everything
rm -rf node_modules src/frontend/node_modules
rm -rf dist src/frontend/dist
rm package-lock.json src/frontend/package-lock.json

# Reinstall
npm install
cd src/frontend && npm install && cd ../..

# Try build
npm run build

Tests failing

Problem: Test environment or outdated snapshots

Solution:

# Update dependencies
npm install

# Update snapshots
npm test -- -u

# Run specific test
npm test -- <test-name>

---

Getting More Help

Diagnostic Information

When asking for help, include:

1. System Info:

   node --version
   npm --version
   uname -a  # or systeminfo on Windows
   

2. Error Messages:
   • Full error text from terminal
   • Browser console errors (F12)
   • Screenshots if helpful
3. Steps to Reproduce:
   • What you did
   • What you expected
   • What actually happened

Check Logs

Backend Logs:

# If configured, check logs folder
cat logs/error.log
tail -f logs/error.log  # Watch in real-time

Browser Console:

1. Open developer tools (F12)
2. Go to Console tab
3. Look for red error messages
4. Copy full error text

Database Queries:

# Enable query logging in backend
DEBUG=* npm run dev

Where to Get Help

1. Documentation: Read FAQ.md and other docs
2. Search Issues: GitHub Issues
3. Ask Community: GitHub Discussions
4. Report Bug: New Issue

Bug Report Template

**Describe the bug**
A clear description of what the bug is.

**To Reproduce**
Steps to reproduce:
1. Go to '...'
2. Click on '...'
3. See error

**Expected behavior**
What you expected to happen.

**Screenshots**
If applicable, add screenshots.

**Environment**
- OS: [e.g., macOS 12.0, Windows 11, Ubuntu 22.04]
- Node version: [e.g., 18.0.0]
- Browser: [e.g., Chrome 120]

**Additional context**
Any other relevant information.

---

Emergency Recovery

Complete Reset (Nuclear Option)

⚠️ WARNING: This deletes all data!

# 1. Backup first!
cp src/backend/data/tracker.db ~/tracker-backup-$(date +%Y%m%d).db

# 2. Delete everything
rm -rf node_modules src/frontend/node_modules
rm -rf dist src/frontend/dist
rm package-lock.json src/frontend/package-lock.json
rm src/backend/data/tracker.db

# 3. Fresh install
npm install
cd src/frontend && npm install && cd ../..

# 4. Start fresh
npm run dev

# 5. Restore data from backup (if needed)
cp ~/tracker-backup-*.db src/backend/data/tracker.db

---

Prevention Tips

Avoid Issues

✅ Do:

• Keep Node.js and npm updated
• Backup database regularly
• Test after updates
• Read update notes
• Use supported browsers

❌ Don’t:

• Run multiple instances simultaneously
• Edit database while app is running
• Use old Node.js versions
• Ignore error messages
• Skip backups

Regular Maintenance

Weekly:

• Clear browser cache
• Check for updates
• Verify backups

Monthly:

• Update dependencies
• Optimize database
• Test restore procedure

---

Still stuck? Open an issue with details!

This site is open source. Improve this page.