Skip to main content

Troubleshooting

Common Issues and Solutions

1. Database Connection Failed

Error:

Unable to connect Osas database: SequelizeConnectionError

Solutions:

  • Check PostgreSQL is running: systemctl status postgresql
  • Verify database credentials in .env
  • Ensure database exists: psql -U postgres -l
  • Check network connectivity to database server
  • Verify firewall allows PostgreSQL port (5432)

2. JWT Token Invalid

Error:

{
  "message": "Unauthorized",
  "error": "Invalid token"
}

Solutions:

  • Verify JWT_SECRET in .env matches token generation
  • Check token expiration (JWT_EXPIRATION setting)
  • Ensure Authorization header format: Bearer <token>
  • Generate new token via /api/auth/signin

3. Rate Limit Exceeded

Error:

{
  "message": "You are sending requests too quickly. Please wait 1 second."
}

Solutions:

  • Wait for rate limit window to reset
  • Adjust RATE_LIMIT_WINDOW_MS and RATE_LIMIT_MAX in .env
  • Implement request queuing in client
  • Use batch endpoints where available

4. File Upload Failed

Error:

{
  "message": "File too large"
}

Solutions:

  • Check file size < 10MB
  • Verify resources/temp/img/ directories exist
  • Check disk space: df -h
  • Ensure correct multipart/form-data encoding

5. Courier Webhook Not Working

Error: Webhooks not updating status

Solutions:

  • Verify courier credentials in .env
  • Check webhook endpoint is accessible (not localhost)
  • Validate webhook authentication (Basic Auth, API Key)
  • Check courier status mapping in app/status/
  • Review webhook logs in console
  • Test with webhook testing tools (ngrok, webhook.site)

6. Fee Calculation Returns 0

Error:

{
  "fee": 0
}

Solutions:

  • Verify origin/destination codes are valid
  • Check location data in database
  • Ensure service availability for route
  • Review pricing configuration
  • Check for special pricing rules
  • Validate weight parameter

7. Sequelize Migration Issues

Error:

SequelizeDatabaseError: relation does not exist

Solutions:

  • Run migrations: Check for migration scripts
  • Sync models: db.sequelize.sync({ alter: true })
  • Check model definitions match database schema
  • Verify table names in model files

8. CORS Errors

Error:

Access to fetch blocked by CORS policy

Solutions:

  • Add origin to ORIGIN_CORS environment variable
  • Verify CORS configuration in ondeliv-backend.js
  • Check request includes proper headers
  • Ensure preflight OPTIONS requests are handled

9. Image Not Loading

Error: 404 on image URLs

Solutions:

  • Verify image directories exist:
    • resources/temp/img/pickup/
    • resources/temp/img/delivery/
    • resources/temp/img/agent/
  • Check file permissions
  • Verify image processing with Sharp
  • Check BASEURL environment variable

10. Cron Job Not Running

Error: Lion Parcel pickup not scheduling

Solutions:

  • Verify LIONPARCEL_PICKUP_CRON format is valid
  • Check cron expression: */30 * * * *
  • Review cron job logs in console
  • Ensure Lion Parcel credentials configured
  • Test cron expression: https://crontab.guru

Debug Mode

Enable Verbose Logging:

// Add to ondeliv-backend.js temporarily
app.use((req, res, next) => {
  console.log(`${req.method} ${req.url}`);
  console.log('Headers:', req.headers);
  console.log('Body:', req.body);
  next();
});

Database Query Logging:

// In db.config.js
module.exports = {
  // ... existing config
  logging: console.log,  // Enable SQL query logging
};

Health Check Endpoint

Check Server Status:

curl http://localhost:4220/

Expected Response:

{
  "message": "This backend osas works well for now"
}

Performance Monitoring

Check Database Connection:

// Test database connectivity
const testConnection = async () => {
  try {
    await db.sequelize.authenticate();
    console.log('Database connected');
  } catch (error) {
    console.error('Database connection failed:', error);
  }
};

Monitor Response Times:

Morgan logs include response time in cyan color.

Getting Help

Resources:

  • Review error logs in console
  • Check courier partner documentation
  • Review Sequelize documentation for database issues
  • Check Express.js documentation for routing issues

Contact:

  • Check repository issues
  • Review pull request discussions
  • Contact system administrator
Back to top