Troubleshooting Guide

Comprehensive guide for diagnosing and resolving issues across the INET Wi-Fi Portal system.

🚨 Critical Issues - Immediate Action Required

If you encounter any of these issues, take immediate action and escalate to system administrators:

🔍 Diagnostic Checklist

Before Starting Troubleshooting

  • ✅ Check system status in Admin → Logs
  • ✅ Verify your internet connection
  • ✅ Clear browser cache and cookies
  • ✅ Try refreshing the page
  • ✅ Check if other users are experiencing the same issue

💳 Payment Issues

❌ Customer Cannot Make Payment

Step 1: Check Payment Logs

Go to Admin → Logs → Failed Payments to see recent payment failures.

Step 2: Verify Wave Integration

Check if Wave payment service is operational and API credentials are valid.

Step 3: Check Customer Details

Verify customer phone number format and name requirements are met.

Common Causes:
  • Invalid phone number format (must be 7 digits starting with 2-9)
  • Incomplete customer name (requires first and last name)
  • Wave service temporarily unavailable
  • Network connectivity issues
⚠️ Payment Successful But No Voucher Issued

Step 1: Check PortaBilling Connection

Verify PortaBilling API connectivity and credentials.

Step 2: Manual Voucher Issuance

Go to Admin → Customers, find the customer, and issue a compensatory voucher.

Step 3: Refund Processing

If voucher cannot be issued, process a refund through Wave dashboard.

🌐 Network Connectivity Issues

📶 Access Point Offline

Step 1: Check AP Status

Go to Admin → Access Points and look for offline or unreachable APs.

Step 2: Verify Network Connectivity

Check if the AP has internet connectivity and can reach the portal backend.

Step 3: OpenNDS Configuration

Verify OpenNDS configuration and AuthMon settings on the AP.

Prevention: Set up monitoring alerts for AP status changes.
🔄 Session Not Starting

Step 1: Check Session Logs

Review Admin → Logs → Failed Requests for session start errors.

Step 2: Verify Voucher Status

Check if the voucher is active and not expired or already used.

Step 3: AuthMon Status

Verify OpenNDS AuthMon is polling the backend correctly.

🎫 Ticketing System Issues

📝 Ticket Not Updating

Step 1: Check User Permissions

Verify the user has the correct role to update the ticket.

Step 2: Refresh Page

Try refreshing the browser page and clearing cache.

Step 3: Check System Logs

Review Admin → Logs for any system errors.

🔔 Notifications Not Sending

Step 1: Check Channel Configuration

Go to Admin → Configuration and verify channel settings.

Step 2: Test Message Templates

Use the template preview feature to test message delivery.

Step 3: Verify Customer Contact Info

Ensure customer has valid phone number or email address.

📱 Mobile App Issues

🔐 Mobile App Login Failed

Step 1: Check Auth Key Status

Verify the auth key is active and not expired in the system.

Step 2: Verify Phone Number

Ensure the phone number is registered and active in the system.

Step 3: Check Network Connectivity

Verify the device has internet connectivity and can reach the API.

📊 Data Not Syncing

Step 1: Force Refresh

Pull down to refresh in the mobile app to force data sync.

Step 2: Check Background Sync

Ensure the app has permission for background data refresh.

Step 3: Restart App

Close and reopen the mobile app to reinitialize connections.

⚙️ System Administration Issues

🔧 Database Connection Lost

Step 1: Check Database Service

Verify PostgreSQL service is running and accessible.

Step 2: Check Connection Pool

Review connection pool settings and available connections.

Step 3: Check Network Connectivity

Ensure the application server can reach the database server.

Emergency Action: Contact database administrator immediately.
🔄 Background Jobs Failing

Step 1: Check Job Logs

Review Admin → Logs → Jobs for failed job executions.

Step 2: Verify Scheduler Status

Check if the job scheduler is running and processing jobs.

Step 3: Manual Job Execution

Try running critical jobs manually to identify the issue.

🔍 Diagnostic Tools

System Health Checks

  • Health Endpoint: /healthz - Basic system status
  • Readiness Check: /readyz - Database and service connectivity
  • Admin Logs: Admin → Logs - System error tracking
  • Analytics Dashboard: Admin → Analytics - Performance metrics

Regular Maintenance Checklist

  • ✅ Check system logs daily for errors
  • ✅ Monitor failed payments and requests
  • ✅ Verify access point connectivity
  • ✅ Review ticket SLA compliance
  • ✅ Check background job status
  • ✅ Monitor system performance metrics

📞 Escalation Procedures

When to Escalate

  • Critical Issues: System down, payment failures, security breaches
  • Persistent Problems: Issues that cannot be resolved with standard procedures
  • Data Loss: Any potential loss of customer or system data
  • Security Concerns: Unauthorized access or suspicious activity

Escalation Contacts

  • Technical Issues: System Administrator
  • Billing Problems: Billing Manager
  • Network Issues: Network Operations Team
  • Security Issues: Security Team

💡 Prevention Tips

← Back to Help Index | Quick Reference | © INET Wi‑Fi Portal