Troubleshooting & FAQ
Common errors, solutions, and frequently asked questions
Common Errors & Solutions
| Error | Cause | Solution |
|---|---|---|
"command not found: node" | Node.js not installed or not in system PATH | Re-install from nodejs.org. On Windows, check 'Add to PATH'. Restart terminal. |
Prisma P1001 — cannot reach DB server | DATABASE_URL wrong or DB not running | Verify connection string. Test credentials in TablePlus. Ensure DB instance is active. |
Redis ECONNREFUSED 127.0.0.1:6379 | Local Redis is not running | Start Redis (redis-server) or switch to Upstash by updating REDIS_URL in .env. |
CORS error in browser | CORS_ORIGINS in .env doesn't include the frontend's origin | Set CORS_ORIGINS=http://localhost:3000 in dev. In production, use the real frontend domain (comma-separate multiple origins). |
process.env.X is undefined | .env file missing, misnamed, or wrong folder | File must be named exactly '.env' in the saas-pos-backend root. Enable file extension display on Windows. |
Port 5000 already in use | Another process is using that port | Change PORT=5001 in .env and update NEXT_PUBLIC_API_URL in frontend .env.local. |
Prisma 'drift detected' error | Manual DB changes not in migration files | Development only: run npm run db:reset. ⚠️ WARNING: destroys all data. |
Cloudinary upload fails | Wrong or missing Cloudinary values in the frontend .env.local | Re-copy the Cloud Name and API credentials from the Cloudinary dashboard into saas-pos-frontend/.env.local, and make sure the upload preset exists and is set to Unsigned. |
JWT TokenExpiredError | Access token has expired | Call POST /auth/refresh with the refresh token to obtain a new access token. |
Migration fails in production | Database user lacks migration permissions | Grant the DB user ALTER and CREATE TABLE privileges, or use the Neon/Supabase console. |
Frequently Asked Questions
Can I use MySQL instead of PostgreSQL?
No. POSVelo uses PostgreSQL-specific features (e.g. conditional UPDATE for TOCTOU safety, partial unique indexes with NULLS NOT DISTINCT). Changing databases requires significant code changes.
Can I run without Redis?
No. Redis is required for BullMQ job queues, auth rate limiting, and Socket.IO horizontal scaling. Use Upstash for a free hosted option.
Can backend and frontend share one server?
Yes. Run both with PM2 on ports 5000 and 3000 and use Nginx to route each subdomain to the correct port.
How do I reset a forgotten admin password?
For the platform Super Admin: the seed script skips accounts that already
exist, so either create a replacement account by running
npm run db:seed:super-admin with a different SUPER_ADMIN_EMAIL (password
must be at least 12 characters), or delete the locked-out user row in Prisma
Studio (npm run db:studio) and re-run the seed with the same email. For
tenant users, an Admin can reset passwords from User Management.
Can multiple cashiers use POS simultaneously?
Yes. The atomic checkout uses a TOCTOU-safe conditional UPDATE. Concurrent transactions on the last stock unit will not cause overselling.
How do I back up the database?
Use pg_dump:
Cloud providers (Neon, Supabase) also provide automatic daily point-in-time backups.
Why is receipt printing not working?
Ensure the paper size in Receipt Settings matches your thermal printer (58mm or 80mm). Printing uses the browser print dialog — make sure popup blockers aren't interfering.
How do I add a new subscription plan?
Log in as Super Admin and create the plan in the platform console's plan catalog (name, pricing, limits). If Stripe keys are configured, the matching Stripe Product/Price is created automatically. No code change or migration is needed.
Is there a REST API Postman collection?
Yes. The backend repository ships a full v1 + v2 collection under
postman/ — POSVelo-API.postman_collection.json plus a matching development
environment file and import notes in postman/README.md.
Can I deploy with Docker?
Partially. Both repositories include a Dockerfile, and the backend's
docker-compose.yml runs PostgreSQL and Redis for local development. For
production, the PM2/VPS and cloud-platform paths in the Deployment Guide are
the documented, supported routes.
If your issue isn't listed above, check the backend Pino logs for detailed
error stack traces. Most runtime errors include enough context to identify the
root cause. You can also open Prisma Studio (npm run db:studio) to inspect
and debug data directly.