Skip to content

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:

  1. Check file permissions:
bash
chmod -R 755 /path/to/colibriplus
chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data /path/to/colibriplus
  1. Clear caches:
bash
php colibri cache:clear
php colibri config:clear
php colibri route:clear
php colibri view:clear
  1. Check logs:
bash
tail -f storage/logs/colibriplus.log

Database Connection Issues

Symptoms: "SQLSTATE" errors or database connection refused

Solutions:

  1. Verify database credentials in .env:
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
  1. Test database connection:
bash
php colibri db:test

You must see the following message: 💡 OK. Your app is connected to database: your_database_name

  1. Run migrations if needed:
bash
php colibri migrate --force

Session/Authentication Issues

Symptoms: Users getting logged out frequently or session errors

Solutions:

  1. Check session configuration in .env:
env
SESSION_DRIVER=file|database|redis|cookie
SESSION_LIFETIME=120
  1. Set proper APP_KEY:
bash
php colibri key:generate

Vue.js Frontend Issues

Blank Page or JavaScript Errors

Symptoms: White screen, console errors, or Vue components not loading

Solutions:

  1. Rebuild frontend assets:

    bash
    npm install
    npm run build
  2. 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
  3. Clear browser cache:

    • Hard refresh with Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
    • Clear browser cache and cookies

API Connection Issues

Symptoms: Frontend can't communicate with backend, API errors

Solutions:

  1. Check API base URL configuration:

    • Verify frontend is pointing to correct backend URL
    • Check for CORS issues in browser console
  2. Verify API routes are working:

    bash
    php colibri route:list

File Upload Issues

Symptoms: Images or files not uploading, permission errors

Solutions:

  1. Check upload directory permissions:

    bash
    chmod -R 775 storage/app/public
    chmod -R 775 public/storage
  2. Create symbolic link:

    bash
    php colibri storage:link
  3. Check file size limits:

Often PHP.ini settings are the cause of the issue. Please check the following settings:

  • PHP upload_max_filesize and post_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:

  1. Enable caching:

    bash
    php colibri config:cache
    php colibri route:cache
    php colibri view:cache
  2. Optimize database:

    bash
    php colibri optimize
  3. Check server resources:

    • Monitor CPU and memory usage
    • Consider upgrading hosting plan if needed

Environment Issues

Development vs Production

Common problems:

  1. Debug mode enabled in production:

    env
    APP_DEBUG=false  # Should be false in production
    APP_ENV=production
  2. Missing environment variables:

    • Compare .env.example with your .env file
    • Ensure all required variables are set
  3. Asset compilation issues:

    bash
    # For production
    npm run build
    
    # For development
    npm run dev

General Debugging Steps

When encountering any issue:

  1. Check error logs:

    • Laravel: storage/logs/colibriplus.log
    • Web server: Apache/Nginx error logs
    • Browser console for frontend errors
  2. Enable debug mode temporarily:

    env
    APP_DEBUG=true

    WARNING

    Remember to disable debug mode in production!

  3. Clear all caches:

    bash
    php colibri optimize:clear
    npm run build
  4. Check file permissions:

    bash
    find /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:

  1. Check the error logs for specific error messages
  2. Search for the specific error message online
  3. Ensure you're running supported PHP and Node.js versions
  4. Consider reaching out to support with specific error details

TIP

Always backup your database and files before attempting any fixes, especially in production environments.

Developed by Mansur Terla. www.terla.me