Skip to main content

Troubleshooting Guide

This guide helps you resolve common issues when setting up or running the Qprint platform.

Prerequisites Issues​

Node.js/npm Not Installed​

Error: npm : The term 'npm' is not recognized

Solution: Install Node.js (which includes npm)

  1. Download Node.js from: https://nodejs.org/
  2. Choose the LTS (Long Term Support) version
  3. Run the installer
  4. Restart your terminal/PowerShell
  5. Verify installation: npm -v and node -v

Go Not Installed​

Error: go: command not found

Solution: Install Go

  1. Download from: https://golang.org/dl/
  2. Install Go 1.24 or later
  3. Verify: go version

PostgreSQL Not Running​

Error: connection refused or database connection failed

Solution:

  1. Start PostgreSQL service:
    • Windows: Check Services, start "postgresql-x64" service
    • Linux: sudo systemctl start postgresql
    • Mac: brew services start postgresql
  2. Verify it's running: pg_isready or check port 5432

Backend Issues​

Backend Won't Start​

Symptoms: Backend fails to start or crashes immediately

Common Causes:

  • PostgreSQL database not running
  • Database credentials incorrect in .env file
  • Database doesn't exist
  • Port 8080 already in use

Solutions:

  1. Check Database Connection:

    # Test PostgreSQL connection
    psql -U postgres -d filesharing

  2. Verify .env Configuration:

    DATABASE_URL=postgres://username:password@localhost:5432/filesharing?sslmode=disable
    JWT_SECRET=your-super-secret-jwt-key-change-this-in-production
    PORT=8080

  3. Create Database if Missing:

    CREATE DATABASE filesharing;

  4. Check Port Availability:

    # Windows
    netstat -ano | findstr :8080

    # Linux/Mac
    lsof -i :8080

  5. Manual Backend Test:

    cd backend
    go run cmd/api/main.go

    Expected output:

    Connected to PostgreSQL database
    Server running on port 8080

Database Connection Failed​

Error: Unable to connect to database or connection refused

Solutions:

  1. Verify PostgreSQL is running
  2. Check connection string format in .env
  3. Verify database exists: psql -U postgres -l
  4. Check firewall settings (port 5432)
  5. Verify credentials (username, password)

JWT Secret Not Set​

Error: Authentication fails or tokens are invalid

Solution: Set a strong JWT secret in backend/.env:

JWT_SECRET=your-super-secret-jwt-key-minimum-32-characters-long
Security

Use a strong, random secret in production. Never use default or weak secrets.

Frontend Issues​

Frontend Won't Start​

Symptoms: npm run dev fails or shows errors

Common Causes:

  • Node.js version too old (need 18+)
  • Corrupted node_modules
  • Port 3000 already in use
  • Missing dependencies

Solutions:

  1. Check Node.js Version:

    node -v  # Should be 18.0.0 or higher

  2. Clean Install:

    cd frontend
    rm -rf node_modules package-lock.json
    npm install

  3. Check Port Availability:

    # Windows
    netstat -ano | findstr :3000

    # Linux/Mac
    lsof -i :3000

  4. Use Different Port:

    PORT=3001 npm run dev

Build Errors​

Error: Build fails on Vercel or during npm run build

Common Causes:

  • Missing environment variables
  • TypeScript errors
  • Missing dependencies

Solutions:

  1. Check .env.local file exists
  2. Verify all required environment variables are set
  3. Run npm run build locally to catch errors
  4. Check TypeScript errors: npx tsc --noEmit

Database Issues​

Migration Errors​

Error: Schema initialization fails

Solutions:

  1. Ensure database exists
  2. Check user has CREATE privileges
  3. Review migration files in backend/migrations/
  4. Manually run migrations if needed

Connection Pool Exhausted​

Error: too many connections

Solutions:

  1. Increase PostgreSQL max_connections setting
  2. Reduce connection pool size in Go code
  3. Close unused connections properly
  4. Check for connection leaks

Mobile App Issues​

Flutter Build Fails​

Error: flutter build or flutter run fails

Solutions:

  1. Clean Build:

    flutter clean
    flutter pub get
    flutter run

  2. Check Flutter Version:

    flutter --version  # Should be 3.10+

  3. Check Dependencies:

    flutter pub get
    flutter pub upgrade

Android Build Issues​

Error: Gradle build fails

Solutions:

  1. Check Android SDK is installed
  2. Verify ANDROID_HOME environment variable
  3. Update Gradle wrapper
  4. Clean build: flutter clean && flutter build apk

Windows Build Issues (Shopkeeper App)​

Error: Windows build fails or printing doesn't work

Solutions:

  1. Check SumatraPDF:

    • Ensure SumatraPDF.exe exists in windows/runner/bin/
    • Run scripts/setup_sumatra.ps1 if missing

  2. Check LibreOffice (optional, for Word/PPT):

    • Run scripts/setup_libreoffice.ps1 if needed

  3. Use Build Script:

    cd shopkeeper_app
    build_windows.bat

  4. See Windows Printing Guide for detailed setup

Payment Integration Issues​

Razorpay Webhook Not Working​

Error: Payment webhooks not received

Solutions:

  1. Verify webhook URL is publicly accessible
  2. Check RAZORPAY_WEBHOOK_SECRET matches Razorpay dashboard
  3. Use ngrok for local testing: ngrok http 8080
  4. Check webhook logs in Razorpay dashboard

Payment Order Creation Fails​

Error: Cannot create payment orders

Solutions:

  1. Verify RAZORPAY_KEY_ID and RAZORPAY_KEY_SECRET are set
  2. Check Razorpay account is active
  3. Verify API keys are for correct environment (test/live)
  4. Check Razorpay API status

Email Service Issues​

Emails Not Sending​

Error: Password reset emails not received

Solutions:

  1. Resend API:

    • Verify RESEND_API_KEY is set
    • Check FROM_EMAIL is verified in Resend
    • Review Resend dashboard for errors

  2. SMTP (if using):

    • Verify SMTP credentials
    • Check SMTP port is not blocked
    • Test SMTP connection

  3. Check Logs:

    • Review backend logs for email errors
    • Check spam folder

File Upload Issues​

Upload Fails​

Error: File upload returns error

Solutions:

  1. Check File Size:

    • Max 20MB per file
    • Max 100MB total for batch uploads

  2. Check File Type:

    • Supported: PDF, PNG, JPG, JPEG, DOC, DOCX, PPT, PPTX

  3. Check Storage:

    • Local: Verify uploads/ directory exists and is writable
    • S3: Verify AWS credentials and bucket permissions

  4. Check Permissions:

    # Linux/Mac
    chmod 755 uploads/

    # Windows: Check folder permissions

Files Not Accessible​

Error: Cannot download uploaded files

Solutions:

  1. Verify file exists in storage
  2. Check file path in database
  3. Verify storage backend (local/S3) is accessible
  4. Check file permissions

Deployment Issues​

Vercel Build Fails​

Error: Frontend build fails on Vercel

Solutions:

  1. Check build logs for specific errors
  2. Verify environment variables are set in Vercel
  3. Check next.config.js configuration
  4. Ensure all dependencies are in package.json

Render Deployment Issues​

Error: Backend deployment fails on Render

Solutions:

  1. Verify build command: cd backend && go build -o backend cmd/api/main.go
  2. Check start command: ./backend
  3. Verify all environment variables are set
  4. Check database connection string
  5. Review Render logs for errors

Common Error Messages​

"Authorization required"​

Cause: Missing or invalid JWT token

Solution:

  • Login again to get new token
  • Check token is stored correctly
  • Verify token hasn't expired

"Invalid credentials"​

Cause: Wrong username/password

Solution:

  • Verify username and password
  • Check if account exists
  • Try password reset

"File not found"​

Cause: File doesn't exist or code is incorrect

Solution:

  • Verify file code is correct
  • Check file hasn't been deleted
  • Verify file belongs to user

"Payment order not found"​

Cause: Order ID doesn't exist or belongs to different user

Solution:

  • Verify order ID is correct
  • Check order belongs to current user
  • Verify payment was completed

Getting More Help​

If you're still experiencing issues:

  1. Check Logs:

    • Backend: Check console output
    • Frontend: Check browser console
    • Mobile: Check Flutter logs

  2. Review Documentation:

  3. Common Resources:

  4. Verify Configuration:

    • Check all environment variables
    • Verify database connection
    • Ensure all services are running

Last Updated: January 26, 2026