OMNI-GRC

Troubleshooting Guide

Common issues and solutions for OMNI-GRC installation, configuration, and operation.

Table of Contents

• Installation Issues
• Configuration Issues
• Runtime Issues
• Database Issues
• Scanner Issues
• Performance Issues
• CLI/TUI Issues
• Web UI Issues
• API Issues
• Getting Help

Installation Issues

Issue: “npm install” fails with permission errors

Error:

EACCES: permission denied, access '/usr/local/lib/node_modules'

Solution:

# Option 1: Use nvm (recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Issue: “npx prisma generate” fails

Error:

Error: The datasource.url property is required in your Prisma config file

Solution:

# Ensure DATABASE_URL is set
echo $DATABASE_URL
# If empty, add to .env.local
echo 'DATABASE_URL="postgresql://postgres:postgres@localhost:5432/omni_grc"' >> .env.local

# Then regenerate
npx prisma generate

Issue: “Cannot find module ‘next’”

Solution:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Configuration Issues

Issue: “NEXTAUTH_SECRET” warning

Error:

[warn] NEXTAUTH_SECRET is not set. Using a default secret.

Solution:

# Generate a secure secret
openssl rand -base64 32

# Add to .env.local
echo 'NEXTAUTH_SECRET="your-generated-secret"' >> .env.local

Issue: PostgreSQL connection refused

Error:

P1001: Can't reach database server at `localhost:5432`

Solution:

# Check if PostgreSQL is running
sudo systemctl status postgresql

# Start if not running
sudo systemctl start postgresql

# Enable on boot
sudo systemctl enable postgresql

# Test connection
psql -U postgres -h localhost -c "SELECT version();"

Issue: Redis connection failed (optional feature)

Error:

Error: Redis connection to localhost:6379 failed

Solution:

# Redis is optional - either install it or disable
# Option 1: Install Redis
sudo apt-get install redis-server
sudo systemctl start redis

# Option 2: Disable Redis features
# Comment out in .env.local:
# REDIS_URL="redis://localhost:6379"

Runtime Issues

Issue: Port 3000 already in use

Error:

Error: listen EADDRINUSE: address already in use :::3000

Solution:

# Find process using port 3000
lsof -i :3000
# or on Windows:
netstat -ano | findstr :3000

# Kill the process
kill -9 <PID>

# Or use different port
PORT=3001 npm run dev

Issue: Hot reload not working

Solution:

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

# Restart dev server
npm run dev

Issue: “Module not found” errors after update

Solution:

# Clear Next.js cache and rebuild
rm -rf .next
npm run build
npm run dev

Database Issues

Issue: Migration failed

Error:

Error: P3009: Migration XX could not be applied

Solution:

# Reset database (WARNING: deletes all data)
npx prisma migrate reset

# Or fix manually and force
npx prisma db push --accept-data-loss

Issue: Database out of sync with schema

Solution:

# Push schema without creating migration
npx prisma db push

# Or create new migration
npx prisma migrate dev --name fix_schema

Issue: Seed script fails

Solution:

# Check if database is empty first
psql -U postgres -d omni_grc -c "\dt"

# Run seed manually
npx tsx prisma/seed.ts

# Or reset and seed
npx prisma migrate reset --skip-seed
npx prisma db seed

Issue: Slow database queries

Solution:

-- Check for missing indexes
SELECT schemaname, tablename, indexname
FROM pg_indexes
WHERE schemaname = 'public'
ORDER BY tablename;

-- Analyze query performance
EXPLAIN ANALYZE SELECT * FROM findings WHERE severity = 'critical';

-- Add indexes if needed
CREATE INDEX idx_findings_severity ON findings(severity);
CREATE INDEX idx_findings_status ON findings(status);

Scanner Issues

Issue: Scanner not available

Symptoms: Scanner shows as “Unavailable” in UI

Solution:

# Check if scanner is installed
which trivy
which prowler
which semgrep

# Install missing scanner
# Trivy
brew install trivy
# or
wget https://github.com/aquasecurity/trivy/releases/download/v0.48.0/trivy_0.48.0_Linux-64bit.tar.gz
tar zxvf trivy_0.48.0_Linux-64bit.tar.gz
sudo mv trivy /usr/local/bin/

# Prowler
pip install prowler

# Semgrep
pip install semgrep

Issue: Scanner execution fails

Error:

Scanner execution failed: Command not found

Solution:

# Add scanner to PATH
export PATH=$PATH:/usr/local/bin:/opt/homebrew/bin

# Or configure absolute path in settings
# Settings → Integrations → Scanners
# Set full path: /usr/local/bin/trivy

Issue: Scanner timeout

Solution:

# Increase timeout in .env.local
SCANNER_TIMEOUT=1800000  # 30 minutes in milliseconds

Performance Issues

Issue: Slow application startup

Solution:

# Build for production
npm run build
npm run start

# Or optimize development
# Clear .next cache
rm -rf .next

# Disable source maps in development
NEXT_PUBLIC_SOURCE_MAPS=false npm run dev

Issue: High memory usage

Solution:

# Increase Node.js memory limit
NODE_OPTIONS=--max-old-space-size=4096 npm run dev

# Or for production
NODE_OPTIONS=--max-old-space-size=4096 npm run start

Issue: Database connection pool exhausted

Error:

Error: P2024: Timed out fetching a new connection from the connection pool

Solution:

# Increase connection pool in .env.local
DATABASE_POOL_MIN=2
DATABASE_POOL_MAX=20
DATABASE_CONNECTION_TIMEOUT=60000

CLI/TUI Issues

Issue: CLI commands not recognized

Error:

bash: omni-grc: command not found

Solution:

# Use npm run script
npm run cli -- dashboard

# Or create alias
alias omni='cd /path/to/OMNI-GRC && npm run cli --'
omni dashboard

Issue: TUI not rendering correctly

Symptoms: Broken borders, misaligned text

Solution:

# Check terminal size (minimum 80x24)
echo $COLUMNS x $LINES

# Set correct TERM
export TERM=xterm-256color

# Try different terminal emulator
# Recommended: iTerm2, Windows Terminal, Alacritty

# Reset terminal
reset
npm run tui

Issue: TUI colors not showing

Solution:

# Enable 256 colors
export TERM=xterm-256color

# Or disable colors
npm run tui -- --no-color

Issue: TUI keyboard shortcuts not working

Solution:

# Some terminals have conflicting bindings
# Use alternative keys:
# - Arrow keys instead of j/k
# - f for filter instead of /
# - Check terminal preferences for key binding conflicts

Web UI Issues

Issue: Page not loading / blank screen

Solution:

# Check browser console for errors (F12)

# Clear browser cache
# Chrome: Ctrl+Shift+Del
# Firefox: Ctrl+Shift+Del

# Hard refresh
# Chrome/Firefox: Ctrl+Shift+R

# Check if server is running
curl http://localhost:3000/api/health

Issue: “Failed to fetch” errors

Solution:

# Ensure API server is running
npm run dev

# Check API URL in browser console
# Should be: http://localhost:3000/api

# Verify CORS settings in .env.local
CORS_ORIGIN=http://localhost:3000

Issue: Authentication loop / session issues

Solution:

# Clear browser cookies
# Chrome: chrome://settings/cookies
# Firefox: Preferences → Privacy & Security → Cookies

# Regenerate NextAuth secret
openssl rand -base64 32 > .nextauth-secret
# Add to .env.local

# Restart server
npm run dev

Issue: Ant Design styles not loading

Solution:

# Clear Next.js cache
rm -rf .next

# Reinstall dependencies
rm -rf node_modules
npm install

# Restart dev server
npm run dev

API Issues

Issue: 401 Unauthorized

Solution:

# Authenticate first
npm run cli -- auth login

# Or use API key
curl -H "Authorization: Bearer your-api-key" \
     http://localhost:3000/api/scans

Issue: 429 Rate Limited

Solution:

# Increase rate limit in .env.local
RATE_LIMIT_MAX_REQUESTS=1000
RATE_LIMIT_WINDOW=900000  # 15 minutes

Issue: API returns 500 Internal Server Error

Solution:

# Check server logs
npm run dev

# Check database connection
psql -U postgres -d omni_grc -c "SELECT 1;"

# Check API endpoint
curl -v http://localhost:3000/api/health

Common Error Messages

“ECONNREFUSED”

• Cause: Server not running or wrong port
• Solution: Start server with npm run dev and verify port

“SQLITE_CANTOPEN”

• Cause: Wrong database type (not using PostgreSQL)
• Solution: Ensure DATABASE_URL points to PostgreSQL

“ENOSPC”

• Cause: No disk space
• Solution: Free up disk space, clean node_modules, .next folders

“MODULE_NOT_FOUND”

• Cause: Missing dependencies
• Solution: Run npm install

“ERR_INVALID_ARG_TYPE”

• Cause: Node.js version mismatch
• Solution: Use Node.js 18.x or higher

Debugging Tips

Enable Verbose Logging

# Add to .env.local
LOG_LEVEL=debug
DEBUG=*

Check System Health

# API health check
curl http://localhost:3000/api/health

# Database connectivity
psql -U postgres -d omni_grc -c "SELECT version();"

# Redis (if using)
redis-cli ping

View Application Logs

# Development logs
npm run dev

# Production logs (with PM2)
pm2 logs omni-grc

# System logs
journalctl -u omni-grc -f

Browser Developer Tools

F12 - Open DevTools
Console tab - JavaScript errors
Network tab - API requests
Application tab - Cookies, localStorage

Getting Help

Self-Help Resources

1. Documentation: Check /docs folder
2. README: Review main README.md
3. CLAUDE.md: Architecture and development guide
4. Search Issues: GitHub Issues

Community Support

1. GitHub Discussions: Ask questions at Discussions
2. Issue Tracker: Report bugs at Issues

Reporting Bugs

When reporting an issue, include:

**Environment:**
- OS: [e.g., Ubuntu 22.04]
- Node.js version: [output of `node --version`]
- PostgreSQL version: [output of `psql --version`]
- OMNI-GRC version: [e.g., 0.1.0]

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

**Expected Behavior:**
A clear description of what you expected to happen.

**Actual Behavior:**
What actually happened.

**Logs:**

Paste relevant log output here

**Screenshots:**
If applicable, add screenshots.

Preventive Maintenance

Regular Tasks

# Weekly: Update dependencies
npm update

# Monthly: Rebuild
rm -rf node_modules .next
npm install
npm run build

# Quarterly: Database maintenance
psql -U postgres -d omni_grc -c "VACUUM ANALYZE;"

Backup Strategy

# Daily database backup
pg_dump -U postgres omni_grc > backup-$(date +%Y%m%d).sql

# Weekly file backup
tar -czf uploads-backup-$(date +%Y%m%d).tar.gz ./uploads

Monitoring

# Set up health check monitoring
while true; do
  curl -s http://localhost:3000/api/health || echo "Service down!"
  sleep 60
done

---

Still stuck? Open an issue on GitHub with detailed information about your problem.