Pritunl: The Open-Source VPN Solution — Complete Guide

Troubleshooting Common Pritunl Installation and Connection Issues

1) Service fails to start / crashes

• Check services
  • sudo systemctl status pritunl
  • sudo systemctl status mongod
• Common fixes
  • Reinstall correct packages for your OS release (use the matching Pritunl + MongoDB repos).
  • Restore missing Python deps by reinstalling distro Python packages or Pritunl package.
  • If systemd unit missing for mongod, install/start mongodb-org per docs.

2) Pritunl can’t connect to MongoDB (Connection refused / ServerSelectionTimeoutError)

• Symptoms: errors referencing localhost:27017, connection refused, timeouts.
• Steps
  1. Verify mongod is running: sudo systemctl status mongod
  2. Check mongod logs (/var/log/mongodb/mongod.log) for startup errors.
  3. Confirm repo and MongoDB version compatibility with your Ubuntu/CentOS release.
  4. For remote DB: verify network / firewall, correct mongodb URI, and that the DB accepts connections from the host.
  5. Restart services: sudo systemctl restart mongod pritunl
  6. If DB corrupted or incompatible, restore from mongodump/mongorestore backup.

3) Installation fails (package 404, checksum mismatch, repo sync)

• Symptoms: apt/yum errors: 404 Not Found, unexpected file size, checksum mismatch.
• Steps
  1. sudo apt-get clean && sudo rm -rf /var/cache/apt/archives/ (or clear yum/dnf cache)
  2. sudo apt update (or yum makecache)
  3. Ensure correct Pritunl repository entry for your distro codename (e.g., bionic, focal, noble).
  4. If checksum/mirror errors persist, wait briefly and retry (mirror sync) or try alternate mirror/region.

4) Missing Python modules or pkg_resources / import errors after upgrade

• Cause: wrong repo for OS, broken system Python, or package mismatch.
• Fix
  • Reinstall Pritunl and required Python packages via the distribution packages in docs.
  • If system Python was modified, restore system Python packages or reinstall the OS Python packages.

5) Clients drop unexpectedly / connection instability (OpenVPN or WireGuard)

• Symptoms: repeated connect/disconnect logs, UI slow, client pool lost.
• Common causes
  • Database performance or latency (writes/queries slow, Atlas throttling).
  • Server overload or resource exhaustion.
  • Network interruptions between Pritunl and MongoDB.
  • Newer pyMongo defaults increasing write concern causing DB slowness.
• Fix / mitigation
  1. Monitor CPU, memory, and DB metrics; scale DB or server if needed.
  2. Use a local MongoDB primary if remote DB connectivity is unstable.
  3. Temporarily stop Pritunl servers and restart service to clear stuck state.
  4. Clear cache/repair: sudo pritunl clear-message-cache; sudo pritunl destroy-secondary; sudo pritunl repair-database

6) UI slow or unresponsive

• Causes: DB query delays, large/tailable cursors, capped collection issues.
• Steps
  • Inspect /var/log/pritunl.log and MongoDB logs for slow queries.
  • Restart Pritunl after stopping servers in UI if necessary.
  • Use repair commands above. Consider upgrading DB hardware or using appropriate Atlas tier.

Useful commands (run as root or with sudo)

• Check services:
  • sudo systemctl status pritunl
  • sudo systemctl status mongod
• Restart services:
  • sudo systemctl restart mongod pritunl
• Pritunl repair/cleanup:
  • sudo pritunl clear-message-cache
  • sudo pritunl destroy-secondary
  • sudo pritunl repair-database
• Backup/restore DB:
  • mongodump –db=pritunl
  • mongorestore –db=pritunl dump

Quick decision guidance

• If MongoDB is not running → focus on mongod startup and logs.
• If repo/package errors → clean package cache and confirm correct repo for OS.
• If clients disconnect but DB reachable → investigate DB performance and restart Pritunl servers.

If you want, I can produce a short checklist tailored to your OS/version (Ubuntu 24.04, 22.04, CentOS, etc.) with exact repo commands and package names.