Troubleshooting

This guide helps you resolve common issues when installing, configuring, or using Laravel Nusa.

Installation Issues

PHP SQLite Extension Missing

Error: could not find driver or PDO SQLite driver not found

Solution: Install the PHP SQLite extension:

bash

# Ubuntu/Debian
sudo apt-get install php8.2-sqlite3

# CentOS/RHEL/Fedora
sudo yum install php-sqlite3
# or
sudo dnf install php-sqlite3

# macOS with Homebrew
brew install [email protected]

# Windows (uncomment in php.ini)
extension=pdo_sqlite
extension=sqlite3

Verify installation:

bash

php -m | grep sqlite
# Should show: pdo_sqlite, sqlite3

Composer Installation Fails

Error: Package not found or Version conflicts

Solutions:

Clear Composer cache:

bash

composer clear-cache
composer install --no-cache

Update Composer:
bash
```
composer self-update
```
Check PHP version:
bash
```
php -v
# Ensure PHP >= 8.2
```

Install with specific version:

bash

composer require creasi/laravel-nusa:^0.1

Laravel Version Compatibility

Error: Package requires Laravel X.Y but you have Z.A

Solution: Check compatibility matrix:

Laravel Nusa	Laravel Versions
0.1.x	9.0 - 12.x

Update Laravel or use compatible version:

bash

# Update Laravel
composer update laravel/framework

# Or install compatible Nusa version
composer require creasi/laravel-nusa:^0.1

Database Issues

SQLite Database Not Found

Error: database disk image is malformed or no such file

Solutions:

Check file exists:

bash

ls -la vendor/creasi/laravel-nusa/database/nusa.sqlite

Reinstall package:

bash

composer remove creasi/laravel-nusa
composer require creasi/laravel-nusa

Check file permissions:

bash

chmod 644 vendor/creasi/laravel-nusa/database/nusa.sqlite

Database Connection Errors

Error: SQLSTATE[HY000] [14] unable to open database file

Solutions:

Check database path:

php

// In tinker
config('database.connections.nusa.database')

Verify file permissions:

bash

# Make directory writable
chmod 755 vendor/creasi/laravel-nusa/database/

# Make file readable
chmod 644 vendor/creasi/laravel-nusa/database/nusa.sqlite

Test connection:

bash

php artisan tinker
>>> DB::connection('nusa')->getPdo()

Foreign Key Constraint Errors

Error: FOREIGN KEY constraint failed

Solution: Enable foreign key constraints:

php

// In config/database.php
'nusa' => [
    'driver' => 'sqlite',
    'database' => database_path('nusa.sqlite'),
    'foreign_key_constraints' => true, // Add this
],

Configuration Issues

Routes Not Working

Error: Route [nusa.provinces.index] not defined

Solutions:

Check if routes are enabled:

bash

# In .env
CREASI_NUSA_ROUTES_ENABLE=true

Clear route cache:

bash

php artisan route:clear
php artisan config:clear

Verify service provider is loaded:

bash

php artisan config:show app.providers | grep Nusa

Check route registration:
bash
```
php artisan route:list | grep nusa
```

API Endpoints Return 404

Error: 404 Not Found for /nusa/provinces

Solutions:

Check route prefix:

bash

# In .env
CREASI_NUSA_ROUTES_PREFIX=nusa

Verify web server configuration:

apache

# Apache .htaccess
RewriteEngine On
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule ^(.*)$ index.php [QSA,L]

Test with full URL:

bash

curl http://your-app.test/index.php/nusa/provinces

Configuration Cache Issues

Error: Configuration changes not taking effect

Solution: Clear configuration cache:

bash

php artisan config:clear
php artisan config:cache
php artisan route:clear

Model and Query Issues

Model Not Found Errors

Error: Class 'Creasi\Nusa\Models\Province' not found

Solutions:

Check autoloader:
bash
```
composer dump-autoload
```
Verify package installation:
bash
```
composer show creasi/laravel-nusa
```

Check namespace import:

php

use Creasi\Nusa\Models\Province; // Add this

Empty Query Results

Error: Models return empty collections

Solutions:

Test database connection:

bash

php artisan tinker
>>> DB::connection('nusa')->table('provinces')->count()

Check table names:

bash

>>> Schema::connection('nusa')->getTableListing()

Verify data exists:

bash

sqlite3 vendor/creasi/laravel-nusa/database/nusa.sqlite
.tables
SELECT COUNT(*) FROM provinces;

Relationship Errors

Error: Call to undefined relationship

Solution: Check relationship methods exist:

php

// Correct usage
$province = Province::find('33');
$regencies = $province->regencies; // Not regency()

// Available relationships
$province->regencies;  // HasMany
$province->districts;  // HasMany  
$province->villages;   // HasMany

Performance Issues

Slow Query Performance

Problem: Queries taking too long

Solutions:

Use pagination:

php

// Good
Village::paginate(50);

// Avoid
Village::all(); // 83,762 records!

Select specific columns:

php

Province::select('code', 'name')->get();

Use eager loading:
php
```
Province::with('regencies')->get();
```

Check indexes:

sql

EXPLAIN QUERY PLAN SELECT * FROM villages WHERE province_code = '33';

Memory Limit Exceeded

Error: Fatal error: Allowed memory size exhausted

Solutions:

Increase memory limit:

bash

php -d memory_limit=512M artisan your:command

Use chunking for large datasets:

php

Village::chunk(1000, function ($villages) {
    foreach ($villages as $village) {
        // Process village
    }
});

Optimize queries:

php

// Use select() to limit columns
Village::select('code', 'name')->chunk(1000, $callback);

Development Issues

Submodule Problems

Error: Submodule path 'workbench/submodules/wilayah': checked out 'abc123'

Solutions:

Initialize submodules:
bash
```
git submodule update --init --recursive
```
Update submodules:
bash
```
git submodule update --remote
```

Reset submodules:

bash

git submodule deinit --all
git submodule update --init --recursive

Docker Issues

Error: Cannot connect to the Docker daemon

Solutions:

Start Docker service:

bash

# Linux
sudo systemctl start docker

# macOS
open -a Docker

Check Docker Compose:
bash
```
docker-compose --version
```

Reset Docker environment:

bash

composer upstream:down
docker system prune -f
composer upstream:up

Import Command Fails

Error: Data import commands fail

Solutions:

Check database connection:

bash

composer testbench tinker
>>> DB::connection()->getPdo()

Verify submodules:
bash
```
ls -la workbench/submodules/
```

Run with verbose output:

bash

composer testbench nusa:import -- --fresh -v

Check disk space:
bash
```
df -h
```

API Issues

CORS Errors

Error: Access to fetch at 'http://localhost/nusa/provinces' from origin 'http://localhost:3000' has been blocked by CORS policy

Solution: Configure CORS in Laravel:

php

// config/cors.php
'paths' => ['api/*', 'nusa/*'],
'allowed_methods' => ['GET'],
'allowed_origins' => ['*'], // Or specific domains
'allowed_headers' => ['*'],

Rate Limiting Issues

Error: 429 Too Many Requests

Solutions:

Check rate limits:

php

// In routes or middleware
Route::middleware(['throttle:60,1'])->group(function () {
    // Your routes
});

Increase limits:

php

Route::middleware(['throttle:1000,1'])->group(function () {
    // Higher limit routes
});

JSON Response Issues

Error: Invalid JSON responses

Solutions:

Check Accept header:

bash

curl -H "Accept: application/json" http://your-app.test/nusa/provinces

Verify API routes:
bash
```
php artisan route:list | grep nusa
```

Getting Help

Debug Information

When reporting issues, include:

bash

# System information
php -v
composer --version
laravel --version

# Package information
composer show creasi/laravel-nusa

# Laravel configuration
php artisan about

# Database connection test
php artisan tinker
>>> DB::connection('nusa')->getPdo()
>>> \Creasi\Nusa\Models\Province::count()

Log Files

Check these log files for errors:

bash

# Laravel logs
tail -f storage/logs/laravel.log

# Web server logs
tail -f /var/log/apache2/error.log
tail -f /var/log/nginx/error.log

# PHP logs
tail -f /var/log/php_errors.log

Support Channels

Documentation - Check this documentation first
GitHub Issues - Report bugs
GitHub Discussions - Community support
Stack Overflow - Tag with laravel-nusa

Creating Bug Reports

Include this information:

Environment: PHP version, Laravel version, OS
Package version: composer show creasi/laravel-nusa
Error message: Full error with stack trace
Steps to reproduce: Minimal code example
Expected behavior: What should happen
Actual behavior: What actually happens

This troubleshooting guide covers the most common issues. If you encounter a problem not listed here, please check the GitHub issues or create a new one with detailed information.

Troubleshooting ​

Installation Issues ​

PHP SQLite Extension Missing ​

Composer Installation Fails ​

Laravel Version Compatibility ​

Database Issues ​

SQLite Database Not Found ​

Database Connection Errors ​

Foreign Key Constraint Errors ​

Configuration Issues ​

Routes Not Working ​

API Endpoints Return 404 ​

Configuration Cache Issues ​

Model and Query Issues ​

Model Not Found Errors ​

Empty Query Results ​

Relationship Errors ​

Performance Issues ​

Slow Query Performance ​

Memory Limit Exceeded ​

Development Issues ​

Submodule Problems ​

Docker Issues ​

Import Command Fails ​

API Issues ​

CORS Errors ​

Rate Limiting Issues ​

JSON Response Issues ​

Getting Help ​

Debug Information ​

Log Files ​

Support Channels ​

Creating Bug Reports ​

Troubleshooting

Installation Issues

PHP SQLite Extension Missing

Composer Installation Fails

Laravel Version Compatibility

Database Issues

SQLite Database Not Found

Database Connection Errors

Foreign Key Constraint Errors

Configuration Issues

Routes Not Working

API Endpoints Return 404

Configuration Cache Issues

Model and Query Issues

Model Not Found Errors

Empty Query Results

Relationship Errors

Performance Issues

Slow Query Performance

Memory Limit Exceeded

Development Issues

Submodule Problems

Docker Issues

Import Command Fails

API Issues

CORS Errors

Rate Limiting Issues

JSON Response Issues

Getting Help

Debug Information

Log Files

Support Channels

Creating Bug Reports