Application Won't Start
Port already in use
# Check what's using port 3000 lsof -i :3000 # Use a different port PORT=3001 npm start
Database connection failed
Verify your DATABASE_URL is correct:
- PostgreSQL: Ensure the database server is running and accessible
- SQLite: Ensure the directory for the database file exists and is writable
Docker image not found
If the setup script shows "image not found", make sure you placed swiftpos-latest.tar.gz in the same directory as docker-compose.yml. You can also load manually:
docker load -i swiftpos-latest.tar.gz docker tag ghcr.io/nullsam/swiftpos:latest swiftpos:latest
License Issues
"License server not configured"
Set the LICENSE_API_ENDPOINT environment variable to the license server URL.
"Could not reach license server"
Check your internet connection. The license server must be reachable from your installation. If behind a firewall, ensure outbound HTTPS traffic to the license server is allowed.
"Invalid license key"
Ensure the key format is SWFT-XXXX-XXXX-XXXX-XXXX (letters and numbers only). The key is case-insensitive.
Performance
Slow on SQLite with many concurrent users
SQLite is best for single-user or low-concurrency environments. For 3+ concurrent cashiers, upgrade to PostgreSQL for better performance.
High memory usage
SwiftPOS typically uses 200-400 MB RAM. If usage is higher, check for:
- Large image uploads (optimize product images)
- Accumulated log files (rotate logs regularly)
- Multiple Node.js processes running (stop duplicates)
Common Errors
"Stock insufficient" during concurrent sales
This is a safety mechanism, not a bug. SwiftPOS prevents overselling with advisory locks (PostgreSQL) or write serialization (SQLite). If you see this frequently, stock levels may be genuinely low.
Receipt printer not working
- Ensure the printer is connected and powered on
- SwiftPOS uses the browser's print dialog — ensure your browser can access the printer
- For thermal printers, use Chrome or Edge for best compatibility
Getting Help
If you're still having issues, contact support at swift@samserver.dev with:
- Your SwiftPOS version
- Deployment method (Docker / Standalone)
- Database type (PostgreSQL / SQLite)
- Error messages from the browser console or server logs