klinik-gunung-docs

Troubleshooting Guide

Comprehensive troubleshooting guide for common issues in the Klinik Gunung Health Screening System

Troubleshooting Guide

This guide provides solutions to common issues and problems that may occur during development, deployment, and usage of the Klinik Gunung Health Screening System.

Table of Contents

Backend Issues

Laravel Application Not Loading

Symptoms:

  • 500 Internal Server Error
  • White screen of death
  • Application timeout

Solutions:

  1. Check Laravel Logs
    tail -f storage/logs/laravel.log
  2. Verify Environment Configuration
    php artisan config:cache
php artisan config:clear
  3. Check File Permissions
    chown -R www-data:www-data storage/
chown -R www-data:www-data bootstrap/cache/
chmod -R 775 storage/
chmod -R 775 bootstrap/cache/
  4. Verify PHP Extensions
    php -m | grep -E "(curl|gd|mbstring|xml|zip)"

API Endpoints Returning 404

Symptoms:

  • API routes not found
  • 404 errors on valid endpoints

Solutions:

  1. Clear Route Cache
    php artisan route:clear
php artisan route:cache
  2. Check Route Registration Verify routes are properly registered in routes/api.php
  3. Verify API Prefix Ensure requests include the correct prefix: /api/v1/

Database Connection Issues

Symptoms:

  • "Database connection refused"
  • PDO connection errors
  • Migration failures

Solutions:

  1. Check Database Credentials Verify .env file has correct database settings
  2. Test Database Connection
    php artisan tinker
DB::connection()->getPdo();
  3. Restart Database Service
    sudo systemctl restart mysql
# or
sudo systemctl restart postgresql

Frontend Issues

Next.js Build Failures

Symptoms:

  • Build process fails
  • TypeScript compilation errors
  • Module resolution issues

Solutions:

  1. Clear Cache and Dependencies
    rm -rf node_modules .next
npm install
  2. Check TypeScript Configuration Verify tsconfig.json and next.config.js are properly configured
  3. Update Dependencies
    npm update

React Query Not Working

Symptoms:

  • Data not loading from API
  • Cache issues
  • Stale data problems

Solutions:

  1. Verify API Base URL Check NEXT_PUBLIC_API_URL environment variable
  2. Clear React Query Cache
    import { useQueryClient } from '@tanstack/react-query'
const queryClient = useQueryClient()
queryClient.clear()
  3. Check Network Tab Use browser dev tools to inspect API requests

Authentication Not Working

Symptoms:

  • Login fails
  • Protected routes accessible without login
  • Token expiration issues

Solutions:

  1. Verify JWT Configuration Check config/jwt.php and .env settings
  2. Clear Authentication Cache
    php artisan config:clear
  3. Check Token Storage Verify tokens are properly stored in localStorage

Database Issues

Migration Errors

Symptoms:

  • Migration fails to run
  • Foreign key constraint errors
  • Table already exists

Solutions:

  1. Reset Migrations
    php artisan migrate:reset
php artisan migrate
  2. Check Migration Order Ensure migrations are properly ordered by timestamp
  3. Manual Database Check
    SHOW TABLES;
DESCRIBE table_name;

Data Integrity Issues

Symptoms:

  • Inconsistent data
  • Foreign key violations
  • Missing relationships

Solutions:

  1. Run Database Seeder
    php artisan db:seed
  2. Check Data Consistency
    php artisan tinker
// Run data validation checks
  3. Backup and Restore
    php artisan backup:run

Authentication Issues

Password Reset Not Working

Symptoms:

  • Password reset emails not sent
  • Invalid reset tokens

Solutions:

  1. Check Mail Configuration Verify .env mail settings
  2. Test Email Sending
    php artisan tinker
Mail::raw('Test email', function($msg) { $msg->to('test@example.com')->subject('Test'); });
  3. Clear Cache
    php artisan config:clear
php artisan cache:clear

Role-Based Access Issues

Symptoms:

  • Users can't access authorized features
  • Incorrect permissions

Solutions:

  1. Verify User Roles
    php artisan tinker
$user = User::find(1);
dd($user->role);
  2. Check Middleware Verify role middleware is properly applied
  3. Clear Permission Cache
    php artisan permission:cache-reset

Deployment Issues

Application Not Accessible

Symptoms:

  • 502 Bad Gateway
  • Connection refused
  • Timeout errors

Solutions:

  1. Check Web Server Configuration
    sudo nginx -t
sudo systemctl status nginx
  2. Verify PHP-FPM
    sudo systemctl status php8.1-fpm
  3. Check Application Logs
    tail -f /var/log/nginx/error.log
tail -f storage/logs/laravel.log

SSL Certificate Issues

Symptoms:

  • HTTPS not working
  • Certificate errors

Solutions:

  1. Check Certificate Installation
    certbot certificates
  2. Renew Certificate
    certbot renew
  3. Verify SSL Configuration Check nginx/ssl configuration

Performance Issues

Slow Page Loads

Symptoms:

  • Slow initial page load
  • High server response time

Solutions:

  1. Enable Caching
    php artisan config:cache
php artisan route:cache
php artisan view:cache
  2. Optimize Database Queries Add database indexes and optimize queries
  3. Check Server Resources
    htop
df -h

Memory Issues

Symptoms:

  • Out of memory errors
  • Application crashes

Solutions:

  1. Increase PHP Memory Limit
    php -i | grep memory_limit
# Update php.ini if needed
  2. Optimize Images and Assets Use proper image formats and compression
  3. Check for Memory Leaks Monitor memory usage with tools like valgrind

Network and Connectivity

CORS Issues

Symptoms:

  • Cross-origin request blocked
  • Preflight request failures

Solutions:

  1. Check CORS Configuration Verify CORS settings in config/cors.php
  2. Update Allowed Origins
    'allowed_origins' => ['https://yourdomain.com'],
  3. Check Request Headers Ensure proper headers are sent from frontend

Cloudflare Tunnel Issues

Symptoms:

  • Tunnel not connecting
  • DNS resolution failures

Solutions:

  1. Check Tunnel Status
    cloudflared tunnel list
  2. Restart Tunnel Service
    sudo systemctl restart cloudflared
  3. Verify DNS Configuration Check Cloudflare DNS settings

File Upload Issues

Upload Failures

Symptoms:

  • Files not uploading
  • Size limit exceeded
  • Invalid file types

Solutions:

  1. Check File Permissions
    chmod 755 storage/
chmod 755 storage/app/public/
  2. Verify PHP Upload Settings
    php -i | grep upload
  3. Check Storage Link
    php artisan storage:link

Image Display Issues

Symptoms:

  • Images not showing
  • Broken image links

Solutions:

  1. Verify Storage Link
    ls -la public/storage
  2. Check File Paths Ensure correct paths in database
  3. Clear Browser Cache Hard refresh or clear browser cache

Getting Help

If these solutions don't resolve your issue:

  1. Check Application Logs
    tail -f storage/logs/laravel.log
tail -f ~/.npm/_logs/*.log
  2. Enable Debug Mode Set APP_DEBUG=true in .env
  3. Collect System Information
    php --version
node --version
mysql --version
  4. Contact Support
    • Create an issue on GitHub
    • Check existing issues
    • Contact the development team

Preventive Measures

Regular Maintenance

  1. Update Dependencies
    composer update
npm update
  2. Monitor Logs Set up log monitoring and alerts
  3. Backup Regularly
    php artisan backup:run

Performance Monitoring

  1. Monitor Server Resources Use tools like htop, iotop, nmon
  2. Database Optimization
    php artisan db:monitor
  3. Error Tracking Implement error tracking services

This troubleshooting guide is continuously updated. If you encounter an issue not covered here, please contribute by documenting the solution.

Cloudflare Tunnel Setup

Complete guide for setting up Cloudflare Tunnel to securely expose the Klinik Gunung application to the internet

Cross-Origin Resource Sharing (CORS)

Comprehensive guide to configuring CORS for the Klinik Gunung Health Screening System with Laravel backend and Next.js frontend