Appearance

Troubleshooting Guide ​

Common issues, error messages, debugging techniques, and solutions for OmniSuite CMS.

Table of Contents ​

  1. Common Issues
  2. Error Messages
  3. Debugging Techniques
  4. Log File Locations
  5. Support Resources

Common Issues ​

Installation Issues ​

Issue: Installer Not Loading ​

Symptoms:

  • Blank page at /install
  • 404 error
  • Server error

Solutions:

  1. Check file permissions
  2. Verify .env file exists
  3. Check PHP version (8.2+)
  4. Verify web server configuration
  5. Check error logs

Issue: Database Connection Failed ​

Symptoms:

  • "Database connection failed" error
  • Cannot connect to database

Solutions:

  1. Verify database credentials in .env
  2. Check database server is running
  3. Verify database exists
  4. Check user permissions
  5. Test connection manually

Issue: Permission Denied Errors ​

Symptoms:

  • "Permission denied" errors
  • Cannot write files
  • Upload failures

Solutions:

bash
# Set correct permissions
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod -R 775 storage bootstrap/cache
chmod 600 .env

Configuration Issues ​

Issue: 500 Internal Server Error ​

Symptoms:

  • 500 error on pages
  • Server error messages

Solutions:

  1. Check error logs: storage/logs/laravel.log
  2. Clear cache: php artisan config:clear
  3. Check file permissions
  4. Verify .env configuration
  5. Check PHP error logs

Issue: White Screen of Death ​

Symptoms:

  • Blank white page
  • No error message

Solutions:

  1. Enable error display in .env: APP_DEBUG=true
  2. Check storage/logs/laravel.log
  3. Verify PHP version
  4. Check memory limit
  5. Review recent changes

Module Issues ​

Issue: Module Not Appearing ​

Symptoms:

  • Module not in menu
  • Cannot access module

Solutions:

  1. Check module is enabled in Module Settings
  2. Verify user has permissions
  3. Clear cache
  4. Check module status
  5. Review module logs

Issue: Module Not Working ​

Symptoms:

  • Module errors
  • Features not functioning

Solutions:

  1. Check module is enabled
  2. Verify permissions
  3. Check error logs
  4. Review module settings
  5. Test in different browser

Error Messages ​

Common Error Messages ​

"Class not found" ​

Cause: Autoloader issue

Solution:

bash
composer dump-autoload
php artisan config:clear

"Table doesn't exist" ​

Cause: Migration not run

Solution:

bash
php artisan migrate

"Permission denied" ​

Cause: File permission issue

Solution:

bash
chmod -R 775 storage bootstrap/cache

"Token mismatch" ​

Cause: CSRF token issue

Solution:

  1. Clear browser cache
  2. Clear application cache
  3. Check session configuration

"Route not found" ​

Cause: Route not registered

Solution:

bash
php artisan route:clear
php artisan route:cache

Debugging Techniques ​

Enable Debug Mode ​

Development ​

.env:

env
APP_DEBUG=true
APP_ENV=local

Warning: Never enable in production!

Check Logs ​

Application Logs ​

Location: storage/logs/laravel.log

View:

bash
tail -f storage/logs/laravel.log

Server Logs ​

Apache:

  • Error log: /var/log/apache2/error.log
  • Access log: /var/log/apache2/access.log

Nginx:

  • Error log: /var/log/nginx/error.log
  • Access log: /var/log/nginx/access.log

Database Debugging ​

Check Queries ​

Enable Query Log:

php
DB::enableQueryLog();
// Your code
dd(DB::getQueryLog());

Test Connection ​

bash
php artisan tinker
DB::connection()->getPdo();

Cache Debugging ​

Clear All Caches ​

bash
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

Check Cache ​

bash
php artisan config:cache
php artisan route:cache

Log File Locations ​

Application Logs ​

Main Log:

  • storage/logs/laravel.log

Daily Logs:

  • storage/logs/laravel-YYYY-MM-DD.log

Server Logs ​

Apache ​

Error Log:

  • /var/log/apache2/error.log
  • /var/log/httpd/error_log (CentOS)

Access Log:

  • /var/log/apache2/access.log
  • /var/log/httpd/access_log (CentOS)

Nginx ​

Error Log:

  • /var/log/nginx/error.log

Access Log:

  • /var/log/nginx/access.log

PHP Logs ​

PHP Error Log:

  • Check php.ini for error_log setting
  • Usually: /var/log/php_errors.log

Database Logs ​

MySQL:

  • /var/log/mysql/error.log
  • Check MySQL configuration

PostgreSQL:

  • Check PostgreSQL log directory

Support Resources ​

Documentation ​

Available Documentation:

  • Installation guides
  • Module documentation
  • Settings guides
  • Feature management
  • API documentation

Self-Help ​

Steps:

  1. Check documentation
  2. Review troubleshooting guides
  3. Check error logs
  4. Search for similar issues
  5. Review recent changes

Getting Help ​

Before Contacting Support:

  1. Gather information:

    • Error messages
    • Log files
    • Steps to reproduce
    • System information

  2. Check:

    • Documentation
    • Troubleshooting guides
    • Known issues

  3. Provide:

    • Detailed description
    • Error messages
    • Log excerpts
    • System details

Last Updated: [Date will be updated during final review]

Released under the MIT License.

Copyright © 2024 OmniSuite CMS