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 | FRONTEND_URL in .env doesn't match frontend | Set FRONTEND_URL=http://localhost:3000 in dev. In production, use the real domain. |
process.env.X is undefined | .env file missing, misnamed, or wrong folder | File must be named exactly '.env' in the 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 credentials | Re-copy Cloud Name, API Key, and API Secret from the Cloudinary dashboard into .env. |
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?
Open Prisma Studio (npm run db:studio), find the user, and update the passwordHash field using bcrypt or the seed-super-admin script.
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?
Plans are a Prisma enum. Add the plan value in schema.prisma, create a migration, and update the subscription logic in the tenant settings service.
Is there a REST API Postman collection?
Not included in this release. Use the API Reference section to build your collection. A Postman/Bruno collection is planned for v1.1.
Can I deploy with Docker?
Docker support is on the roadmap (v1.1). For now, use PM2 on VPS or cloud platform deployments as described in the Deployment Guide.
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.