Skip to main content

​
Overview

This guide covers common issues you may encounter with GB App and how to resolve them.

​
Application Issues

​
500 Internal Server Error

  • White screen or generic error page
  • No detailed error message
  • Application won’t load
Check Laravel logs:
docker compose exec app tail -100 storage/logs/laravel.log
Check web server logs:
docker compose logs nginx
Check PHP errors:
docker compose exec app tail -100 /var/log/php8.2-fpm.log
  1. Check file permissions:
docker compose exec app chmod -R 775 storage bootstrap/cache
docker compose exec app chown -R www-data:www-data storage bootstrap/cache
  1. Clear cache:
docker compose exec app php artisan optimize:clear
  1. Check .env file exists:
docker compose exec app ls -la .env
  1. Verify APP_KEY is set:
docker compose exec app php artisan key:generate
  1. Check database connection:
docker compose exec app php artisan tinker
>>> DB::connection()->getPdo();

​
Class Not Found Errors

Class 'App\Models\User' not found
  1. Regenerate autoload files:
docker compose exec app composer dump-autoload
  1. Clear compiled files:
docker compose exec app php artisan clear-compiled
  1. Optimize autoloader:
docker compose exec app composer install --optimize-autoloader

​
CSRF Token Mismatch

CSRF token mismatch
419 Page Expired
  1. Clear browser cookies
  2. Check session configuration:
.env
SESSION_DRIVER=database
SESSION_LIFETIME=120
  1. Verify session table exists:
docker compose exec app php artisan session:table
docker compose exec app php artisan migrate
  1. Check APP_URL matches current URL:
.env
APP_URL=http://localhost
  1. Clear cache:
docker compose exec app php artisan config:clear

​
Database Issues

​
Cannot Connect to Database

PDOException: SQLSTATE[HY000] [2002] Connection refused
Access denied for user
  1. Check database container is running:
docker compose ps
  1. Test connection from app container:
docker compose exec app mysql -h db -u root -ppasswordr GBapp
  1. Check database logs:
docker compose logs db
  1. Verify .env database settings:
.env
DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=GBapp
DB_USERNAME=root
DB_PASSWORD=passwordr
  1. For Docker, DB_HOST must be ‘db’ (service name)
  2. Restart database container: 
docker compose restart db
  1. Check database exists:
docker compose exec db mysql -u root -ppasswordr -e "SHOW DATABASES;"
  1. Create database if missing:
docker compose exec db mysql -u root -ppasswordr -e "CREATE DATABASE GBapp;"
  1. Clear config cache:
docker compose exec app php artisan config:clear

​
Migration Errors

SQLSTATE[42S01]: Base table or view already exists
SQLSTATE[42S02]: Base table or view not found
  1. Check migration status:
docker compose exec app php artisan migrate:status
  1. Rollback last migration:
docker compose exec app php artisan migrate:rollback
  1. Fresh migration (destroys data):
docker compose exec app php artisan migrate:fresh --seed
  1. Fix specific migration: Edit the problematic migration file, then:
docker compose exec app php artisan migrate:refresh

​
SQL Server Connection Issues

SQLSTATE[01000]: Adaptive Server connection failed
SQLSTATE[08001]: Unable to complete login process
  1. Check SQL Server drivers installed:
docker compose exec app php -m | grep sqlsrv
Should show:
pdo_sqlsrv
sqlsrv
  1. Verify connection settings:
.env
DB_CONNECTION=sqlsrv
DB_HOST=sqlserver.domain.com
DB_PORT=1433
DB_DATABASE=GBapp
DB_USERNAME=sa
DB_PASSWORD=password
SQLSRV_ENCRYPT=true
SQLSRV_TRUST_SERVER_CERTIFICATE=true
  1. Try trusting server certificate:
.env
SQLSRV_TRUST_SERVER_CERTIFICATE=true
  1. Test connection with sqlcmd:
docker compose exec app sqlcmd -S sqlserver.domain.com -U sa -P password

​
Authentication Issues

​
LDAP Connection Failed

LdapRecordException: Can't contact LDAP server
Error al conectar con Active Directory
  1. Test LDAP connection:
docker compose exec app php artisan tinker

use LdapRecord\Container;
$connection = Container::getDefaultConnection();
$connection->connect();
  1. Check LDAP logs:
docker compose exec app tail -100 storage/logs/laravel.log | grep LDAP
  1. Enable LDAP logging:
.env
LDAP_LOGGING=true
LOG_LEVEL=debug
  1. Verify LDAP settings:
.env
LDAP_HOST=dc.domain.com
LDAP_PORT=389
LDAP_BASE_DN=dc=domain,dc=com
LDAP_USERNAME=cn=bind,dc=domain,dc=com
LDAP_PASSWORD=password
  1. Test with ldapsearch (if available):
ldapsearch -x -H ldap://dc.domain.com -D "cn=bind,dc=domain,dc=com" -w password -b "dc=domain,dc=com"
  1. Check firewall allows LDAP ports:
  • Port 389 (LDAP)
  • Port 636 (LDAPS)
  • Port 3268 (Global Catalog)
  1. Try without SSL first:
.env
LDAP_SSL=false
LDAP_TLS=false
LDAP_PORT=389
  1. Verify bind account credentials

​
User Cannot Login

  1. Check user exists:
docker compose exec app php artisan tinker

User::where('username', 'testuser')->first();
  1. Check is_ldap_user flag:
$user = User::where('username', 'testuser')->first();
$user->is_ldap_user; // Should be false for local users
  1. Reset password:
$user = User::where('username', 'testuser')->first();
$user->password = bcrypt('newpassword');
$user->save();
  1. Verify user exists in AD:
docker compose exec app php artisan tinker

$ldapUser = \App\Ldap\User::where('samaccountname', '=', 'testuser')->first();
$ldapUser->getAttributes();
  1. Check LDAP authentication:
use LdapRecord\Container;
$connection = Container::getDefaultConnection();
$ldapUser = \App\Ldap\User::where('samaccountname', '=', 'testuser')->first();
$connection->auth()->attempt($ldapUser->getDn(), 'password');
  1. Sync user manually:
$authenticator = new \App\Actions\Fortify\AuthenticateUserHybrid();
// User will sync on next successful login

​
Two-Factor Authentication Issues

  1. Disable 2FA for user:
docker compose exec app php artisan tinker

$user = User::where('email', '[email protected]')->first();
$user->two_factor_secret = null;
$user->two_factor_recovery_codes = null;
$user->two_factor_confirmed_at = null;
$user->save();

​
Power BI Integration Issues

​
Cannot Generate Access Token

401 Unauthorized
Invalid client secret
  1. Verify Power BI credentials:
.env
POWERBI_CLIENT_ID=your-app-id
POWERBI_CLIENT_SECRET=your-app-secret
POWERBI_USERNAME=[email protected]
POWERBI_PASSWORD=password
POWERBI_RESOURCE=https://analysis.windows.net/powerbi/api
  1. Test token generation:
docker compose exec app php artisan tinker

$trait = new class {
    use \App\Traits\PowerBITrait;
    public function test() {
        return $this->getUserAccessToken();
    }
};
$trait->test();
  1. Check Azure AD app permissions:
  • Ensure API permissions granted
  • Verify admin consent given
  • Check client secret hasn’t expired
  1. Clear config cache:
docker compose exec app php artisan config:clear

​
Cannot Import Reports

403 Forbidden
Workspace not found
  1. Verify workspace ID is correct
  2. Check service principal has access:
  • Add app to workspace as Member or Admin
  • Verify Power BI service principal enabled in tenant settings
  1. Test API call:
docker compose exec app php artisan tinker

$controller = new \App\Http\Controllers\ImportReportController();
$request = new \Illuminate\Http\Request(['group_id' => 'workspace-id']);
$controller->get_reports($request);

​
Reports Won’t Embed

  • Blank iframe
  • “Unable to load report”
  • Token expired error
  1. Check embed token:
docker compose exec app php artisan tinker

$report = \App\Models\Report::first();
echo $report->token;
echo $report->expiration_date;
  1. Regenerate token:
$report->token = null;
$report->expiration_date = null;
$report->save();
// Token will regenerate on next view
  1. Check browser console for errors
  2. Verify Power BI JavaScript library loaded

​
Docker Issues

​
Container Won’t Start

# Check container status
docker compose ps

# View logs
docker compose logs app
docker compose logs nginx
docker compose logs db
  1. Port conflict:
# Check if port is in use
sudo netstat -tuln | grep 80
sudo netstat -tuln | grep 3306

# Change port in docker-compose.yml
nginx:
    ports:
        - "8080:80"
  1. Build failed:
# Rebuild without cache
docker compose build --no-cache
  1. Permission issues:
# Fix ownership
sudo chown -R $USER:$USER .
  1. Disk space:
# Check disk space
df -h

# Clean Docker
docker system prune -a

​
Permission Denied in Container

# Fix storage permissions
docker compose exec app chmod -R 775 storage bootstrap/cache
docker compose exec app chown -R www-data:www-data storage bootstrap/cache

# If still issues, check SELinux (if enabled)
sudo setenforce 0

​
Performance Issues

​
Slow Page Load

  1. Enable query logging:
DB::enableQueryLog();
// Your code
dd(DB::getQueryLog());
  1. Check debug bar (if installed in dev)
  2. Monitor server resources: 
docker stats gb-app-php gb-app-webserver gb-app-db
  1. Enable caching:
php artisan config:cache
php artisan route:cache
php artisan view:cache
  1. Use Redis for sessions:
.env
CACHE_DRIVER=redis
SESSION_DRIVER=redis
  1. Optimize database queries:
  • Add indexes
  • Use eager loading
  • Cache frequent queries
  1. Enable OPcache (see production guide)
  2. Optimize Composer autoloader: 
composer install --optimize-autoloader --no-dev

​
High Memory Usage

  1. Increase PHP memory limit:
php.ini
memory_limit = 1024M
  1. Check for memory leaks:
docker compose exec app php artisan tinker

echo memory_get_usage() / 1024 / 1024 . ' MB';
  1. Use chunking for large datasets:
User::chunk(100, function ($users) {
    // Process users
});

​
Logging and Debugging

​
Enable Debug Mode (Development Only)

.env
APP_DEBUG=true
LOG_LEVEL=debug
Never enable debug mode in production!

​
View Logs

# Laravel logs
docker compose exec app tail -f storage/logs/laravel.log

# Nginx access logs
docker compose logs -f nginx

# PHP-FPM logs
docker compose exec app tail -f /var/log/php8.2-fpm.log

# MySQL logs
docker compose logs -f db

​
Query Debugging

// Enable query log
DB::enableQueryLog();

// Your queries
$users = User::where('is_ldap_user', true)->get();

// View queries
dd(DB::getQueryLog());

// Log queries
DB::listen(function($query) {
    Log::info($query->sql);
    Log::info($query->bindings);
    Log::info($query->time);
});

​
Getting Help

If you can’t resolve an issue:
  1. Check Laravel logs for detailed error messages
  2. Search Laravel documentation at https://laravel.com/docs
  3. Check package documentation:
  4. Review Power BI API docs at https://learn.microsoft.com/en-us/rest/api/power-bi/

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us