Troubleshooting
This page covers common issues you might encounter with ColibriPlus and their solutions. ColibriPlus is built with Laravel (backend) and Vue.js (frontend), so issues typically fall into one of these categories.
Backend Issues
500 Internal Server Error
Symptoms: White screen or generic server error message
Common causes and solutions:
- Check file permissions:
chmod -R 755 /path/to/colibriplus
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data /path/to/colibriplus
- Clear caches:
php colibri cache:clear
php colibri config:clear
php colibri route:clear
php colibri view:clear
- Check logs:
tail -f storage/logs/colibriplus.log
Database Connection Issues
Symptoms: "SQLSTATE" errors or database connection refused
Solutions:
- Verify database credentials in
.env
:
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password
- Test database connection:
php colibri db:test
You must see the following message: 💡 OK. Your app is connected to database:
your_database_name
- Run migrations if needed:
php colibri migrate --force
Session/Authentication Issues
Symptoms: Users getting logged out frequently or session errors
Solutions:
- Check session configuration in
.env
:
SESSION_DRIVER=file|database|redis|cookie
SESSION_LIFETIME=120
- Set proper APP_KEY:
php colibri key:generate
Vue.js Frontend Issues
Blank Page or JavaScript Errors
Symptoms: White screen, console errors, or Vue components not loading
Solutions:
Rebuild frontend assets:
bashnpm install npm run build
Check for JavaScript errors in browser console:
- Press F12 to open Developer Tools
- Check Console tab for errors
- Look for failed network requests in Network tab
Clear browser cache:
- Hard refresh with
Ctrl+F5
(Windows) orCmd+Shift+R
(Mac) - Clear browser cache and cookies
- Hard refresh with
API Connection Issues
Symptoms: Frontend can't communicate with backend, API errors
Solutions:
Check API base URL configuration:
- Verify frontend is pointing to correct backend URL
- Check for CORS issues in browser console
Verify API routes are working:
bashphp colibri route:list
File Upload Issues
Symptoms: Images or files not uploading, permission errors
Solutions:
Check upload directory permissions:
bashchmod -R 775 storage/app/public chmod -R 775 public/storage
Create symbolic link:
bashphp colibri storage:link
Check file size limits:
Often PHP.ini settings are the cause of the issue. Please check the following settings:
- PHP
upload_max_filesize
andpost_max_size
settings - Web server upload limits
- PHP
memory_limit
settings - PHP
max_execution_time
settings - PHP
max_input_time
settings - PHP
max_input_vars
settings - PHP
max_file_uploads
settings
Performance Issues
Slow Loading Times
Solutions:
Enable caching:
bashphp colibri config:cache php colibri route:cache php colibri view:cache
Optimize database:
bashphp colibri optimize
Check server resources:
- Monitor CPU and memory usage
- Consider upgrading hosting plan if needed
Environment Issues
Development vs Production
Common problems:
Debug mode enabled in production:
envAPP_DEBUG=false # Should be false in production APP_ENV=production
Missing environment variables:
- Compare
.env.example
with your.env
file - Ensure all required variables are set
- Compare
Asset compilation issues:
bash# For production npm run build # For development npm run dev
General Debugging Steps
When encountering any issue:
Check error logs:
- Laravel:
storage/logs/colibriplus.log
- Web server: Apache/Nginx error logs
- Browser console for frontend errors
- Laravel:
Enable debug mode temporarily:
envAPP_DEBUG=true
WARNING
Remember to disable debug mode in production!
Clear all caches:
bashphp colibri optimize:clear npm run build
Check file permissions:
bashfind /path/to/colibriplus -type f -exec chmod 644 {} \; find /path/to/colibriplus -type d -exec chmod 755 {} \; chmod -R 775 storage bootstrap/cache
Getting Help
If you're still experiencing issues after trying these solutions:
- Check the error logs for specific error messages
- Search for the specific error message online
- Ensure you're running supported PHP and Node.js versions
- Consider reaching out to support with specific error details
TIP
Always backup your database and files before attempting any fixes, especially in production environments.