Troubleshooting

Solutions to common issues you might encounter when installing or running ATStatus.

Installation Issues

npm install fails with permission errors

On Windows: Run terminal as Administrator. On Linux/Mac: Use sudo npm install or use a Node version manager (nvm, fnm).

npm run setup fails or hangs

1. Ensure .env file exists. 2. Check Node.js version (18+). 3. Try manual steps: npx prisma generate && npx prisma db push && npm run build

Build fails with TypeScript errors

Run npx prisma generate first. Clear caches with rm -rf node_modules .next && npm install

Database Problems

Database file locked (SQLITE_BUSY)

Stop all running instances. Close Prisma Studio if open. Check for hung processes with ps aux | grep node.

Database not found

Check DATABASE_URL in .env is file:./data.db. Run npx prisma db push to create.

Schema changes not applying

Run npx prisma generate && npx prisma db push after updates.

Authentication / Login Issues

Cannot log in with correct password

Check ADMIN_PASSWORD in .env. Ensure no trailing spaces. Clear browser cookies. Check for rate limiting.

Session expires immediately

Check SESSION_SECRET is set. For HTTP (local), set FORCE_SECURE_COOKIES="false".

2FA codes not working

Verify system time is correct (TOTP is time-based). Try code from 30s ago/ahead. Use backup codes if available.

Monitoring Not Working

Components not updating automatically

1. Verify monitoring is enabled on component. 2. Check URL is accessible from server. 3. Ensure daemon is running: npm run monitor

All monitors show as down

Check network connectivity and DNS. Verify firewall rules (outbound HTTPS). Increase timeout values.

Response times incorrect

Ensure monitor runs regularly (60s recommended). Check response time is measured for your monitor type.

Status Page Display Issues

Status page shows blank/white

Check browser console for JS errors. Verify build completed: npm run build. Ensure .next folder exists.

Components not showing

Verify components exist in admin. Check "Show on Public" is enabled. Ensure components are assigned to status page.

Custom styles not applying

Hard refresh (Ctrl+Shift+R). Clear browser cache. Check CSS syntax. Verify image URLs are accessible.

Email Notifications

Emails not sending

Verify SMTP settings (host, port, user, pass, from). Test with Gmail SMTP first. Check server logs for SMTP errors.

Emails going to spam

Set up SPF, DKIM, DMARC records. Use reputable email service (SendGrid, Mailgun). Ensure "From" matches your domain.

Performance Issues

Pages load slowly

Ensure production build is running (not dev). Check server resources. Optimize images. Consider CDN for high traffic.

Database queries slow

SQLite is fine for ~10k components. For larger installations, use PostgreSQL. Archive old incidents.

High memory usage

Minimum 512MB RAM, 1GB+ recommended. Restart server periodically if memory grows.

Getting Help

If you can't resolve an issue, include these details when reporting:

ATStatus version and Node.js version
Operating system
Error messages (sanitized of secrets)
Steps to reproduce