Troubleshooting Installation Issues

This guide helps you resolve common issues encountered during OmniSuite CMS installation.

Common Error Messages
Permission Issues
Database Connection Errors
PHP Extension Errors
500 Internal Server Error
White Screen of Death
Installer Not Loading
Migration Errors
Seeder Errors
General Troubleshooting Steps

Common Error Messages

"PHP version 8.2.0 or higher required"

Problem: Your server is running an older PHP version.

Solutions:

cPanel:

Go to Select PHP Version
Choose PHP 8.2 or higher
Click Set as current

VPS/Server:

bash

# Check current version
php -v

# Update PHP (Ubuntu/Debian)
sudo apt update
sudo apt install php8.2 php8.2-cli php8.2-fpm php8.2-mysql

# Update PHP (CentOS/RHEL)
sudo yum install php82 php82-php-cli php82-php-fpm

Contact Hosting Provider:

If you can't change PHP version, contact your host
Request PHP 8.2+ upgrade

"Required PHP extension missing"

Problem: A required PHP extension is not installed.

Solutions:

cPanel:

Go to Select PHP Version
Click Extensions
Enable missing extensions:
- mbstring
- xml
- curl
- intl
- zip
- pdo_mysql
Click Save

VPS/Server:

bash

# Ubuntu/Debian
sudo apt install php8.2-mbstring php8.2-xml php8.2-curl php8.2-intl php8.2-zip

# CentOS/RHEL
sudo yum install php82-php-mbstring php82-php-xml php82-php-curl php82-php-intl

Verify Installation:

bash

php -m | grep extension_name

"Directory is not writable"

Problem: Required directories don't have write permissions.

Solutions:

Set Permissions:

bash

# Navigate to installation directory
cd /path/to/your/installation

# Set directory permissions
chmod -R 755 storage
chmod -R 755 bootstrap/cache
chmod -R 755 public

# Set file permissions
chmod 644 .env
chmod 755 artisan

cPanel File Manager:

Right-click directory
Select Change Permissions
Enter 755 for directories
Check Recurse into subdirectories
Click Change Permissions

Verify:

bash

ls -la storage
ls -la bootstrap/cache

Permission Issues

Symptoms

"Permission denied" errors
Cannot write to directory
Files cannot be uploaded
Cache cannot be cleared

Solutions

Check Current Permissions

bash

ls -la

Set Correct Permissions

Directories (755):

bash

chmod -R 755 storage
chmod -R 755 bootstrap/cache
chmod -R 755 public
chmod -R 755 resources

Files (644):

bash

find . -type f -exec chmod 644 {} \;

Executable Files (755):

bash

chmod 755 artisan

Fix Ownership (if needed)

bash

# Find web server user
ps aux | grep -E 'apache|httpd|nginx|www-data'

# Change ownership (example)
sudo chown -R www-data:www-data /path/to/installation

cPanel Specific

Use File Manager
Select files/folders
Right-click → Change Permissions
Set appropriate permissions
Check Recurse for directories

Database Connection Errors

"Access denied for user"

Problem: Database credentials are incorrect or user lacks privileges.

Solutions:

Verify Credentials:
- Double-check username
- Verify password (copy-paste to avoid typos)
- Check database name
Check User Privileges:
sql
```
-- In phpMyAdmin or MySQL client
SHOW GRANTS FOR 'username'@'localhost';
```
1
2
User needs:
- SELECT
- INSERT
- UPDATE
- DELETE
- CREATE
- DROP
- ALTER
Recreate Database User:
- Delete old user
- Create new user with ALL PRIVILEGES
- Test connection
Check Database Host:
- May not be localhost
- Check with hosting provider
- Common alternatives: 127.0.0.1, server IP

"Unknown database"

Problem: Database doesn't exist or name is incorrect.

Solutions:

Verify Database Exists:
- Check in phpMyAdmin
- List all databases
- Verify exact name (case-sensitive)

Create Database:

sql

CREATE DATABASE database_name CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Check Database Name:
- cPanel: Use full name (e.g., username_dbname)
- Verify in cPanel MySQL Databases section

"Can't connect to MySQL server"

Problem: Cannot reach database server.

Solutions:

Check Database Host:
- Try 127.0.0.1 instead of localhost
- Check with hosting provider
- May need specific hostname

Verify Database Server is Running:

bash

# Check MySQL status
sudo systemctl status mysql
# or
sudo systemctl status mariadb

Test Connection:

bash

mysql -u username -p -h hostname database_name

Check Firewall:
- Ensure MySQL port (3306) is open
- Check server firewall rules

PHP Extension Errors

Missing Extension List

If installer shows missing extensions:

Required Extensions:

OpenSSL
PDO
Mbstring
Tokenizer
XML
Ctype
JSON
cURL
Intl

Installation Commands

Ubuntu/Debian:

bash

sudo apt update
sudo apt install php8.2-openssl php8.2-pdo php8.2-mbstring \
  php8.2-tokenizer php8.2-xml php8.2-ctype php8.2-json \
  php8.2-curl php8.2-intl php8.2-zip

CentOS/RHEL:

bash

sudo yum install php82-php-openssl php82-php-pdo php82-php-mbstring \
  php82-php-tokenizer php82-php-xml php82-php-ctype php82-php-json \
  php82-php-curl php82-php-intl

cPanel:

Select PHP Version → Extensions
Enable all required extensions
Click Save

Verify Extensions

bash

php -m

Should show all required extensions in the list.

500 Internal Server Error

Symptoms

Blank page or "500 Internal Server Error"
No specific error message
Site completely inaccessible

Solutions

Check Error Logs

cPanel:

Go to Errors section
View latest error log
Look for specific error message

Server:

bash

# Apache
tail -f /var/log/apache2/error.log

# Nginx
tail -f /var/log/nginx/error.log

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

Common Causes

.htaccess Issues:
- Check .htaccess file exists
- Verify mod_rewrite is enabled
- Check for syntax errors
File Permissions:
- Set correct permissions (see Permission Issues)
- Ensure web server can read files
PHP Errors:
- Check PHP error log
- Enable error display (development only)
- Fix PHP syntax errors
Memory Limit:
- Increase PHP memory_limit
- Check in php.ini or .htaccess

Enable Error Display (Temporary)

In .env:

APP_DEBUG=true

Warning: Only for troubleshooting. Disable in production.

White Screen of Death

Symptoms

Completely blank white page
No error message
Browser shows nothing

Solutions

Step 1: Check Error Logs

bash

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

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

Step 2: Enable Error Display

Temporary (Development Only):

In .env:

APP_DEBUG=true

In config/app.php:

php

'debug' => env('APP_DEBUG', true),

Step 3: Check Common Issues

Missing .env File:

bash

cp .env.example .env
php artisan key:generate

Storage Permissions:

bash

chmod -R 775 storage
chmod -R 775 bootstrap/cache

Composer Dependencies:
bash
```
composer install
```
1

Cache Issues:

bash

php artisan config:clear
php artisan cache:clear
php artisan view:clear

Step 4: Check PHP Errors

Create test.php:

php

<?php
error_reporting(E_ALL);
ini_set('display_errors', 1);
phpinfo();

Access test.php in browser. Delete after testing.

Installer Not Loading

Symptoms

404 error when accessing /install
Blank page
Redirects to home page

Solutions

Check File Structure

Verify files are in correct location:

public/
  index.php
  .htaccess
artisan
.env.example
composer.json

Check .htaccess

Apache: Ensure .htaccess exists in public/ directory:

apache

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

Check mod_rewrite

Apache:

bash

# Check if enabled
apache2ctl -M | grep rewrite

# Enable if not
sudo a2enmod rewrite
sudo systemctl restart apache2

cPanel:

mod_rewrite is usually enabled
Check with hosting provider if issues persist

Check Routes

Verify installer routes exist:

bash

php artisan route:list | grep install

Try Direct Access

Try accessing:

http://yourdomain.com/public/index.php

If this works, .htaccess rewrite is the issue.

Migration Errors

Symptoms

"Migration failed" error
Specific table creation errors
Foreign key constraint errors

Solutions

Check Database Connection

bash

php artisan migrate:status

Run Migrations Manually

bash

# Fresh migration (WARNING: Deletes all data)
php artisan migrate:fresh

# Or step by step
php artisan migrate

Check Specific Migration

bash

# See migration status
php artisan migrate:status

# Rollback last migration
php artisan migrate:rollback

# Run specific migration
php artisan migrate --path=/database/migrations/2024_01_01_000000_create_table.php

Common Migration Issues

Table Already Exists:

bash

# Drop and recreate
php artisan migrate:fresh

Foreign Key Errors:
- Check migration order
- Ensure parent tables exist first
Column Type Errors:
- Verify database supports column types
- Check MySQL version compatibility

Check Database

sql

-- List all tables
SHOW TABLES;

-- Check table structure
DESCRIBE table_name;

Seeder Errors

Symptoms

"Seeder failed" error
Missing data after installation
Specific seeder errors

Solutions

Run Seeders Manually

bash

# Run all seeders
php artisan db:seed

# Run specific seeder
php artisan db:seed --class=SettingSeeder

Check Seeder Files

Verify seeders exist:

bash

ls -la database/seeders/

Common Seeder Issues

Missing Dependencies:
- Ensure migrations ran first
- Check foreign key relationships
Data Conflicts:
- Clear existing data
- Run fresh migration with seed
Permission Errors:
- Check file permissions
- Verify database user privileges

Fresh Start

bash

# Drop all tables and reseed
php artisan migrate:fresh --seed

Warning: This deletes all existing data.

General Troubleshooting Steps

Step 1: Check Requirements

Verify PHP version: php -v
Check extensions: php -m
Verify database connection
Check file permissions

Step 2: Review Logs

Laravel Logs:

bash

tail -f storage/logs/laravel.log

Server Logs:

Apache: /var/log/apache2/error.log
Nginx: /var/log/nginx/error.log
PHP: Check php.ini error_log setting

Step 3: Clear Cache

bash

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

Step 4: Verify Configuration

Check .env File:

bash

cat .env

Verify:

APP_KEY is set
Database credentials are correct
APP_URL matches your domain

Step 5: Test Database

bash

php artisan tinker

Then:

php

DB::connection()->getPdo();

Should connect without errors.

Step 6: Check File Structure

Verify all required files exist:

.env file
composer.json
artisan file
public/index.php
storage/ directory
bootstrap/cache/ directory

Getting Help

Before Seeking Help

Check Error Logs:
- Laravel log
- Server error log
- PHP error log
Document the Error:
- Exact error message
- When it occurs
- Steps to reproduce
Check Documentation:
- Review relevant guides
- Search for similar issues

Support Resources

Application Support:
- Check support channels provided
- Include error logs and details
Hosting Provider:
- Contact for server-related issues
- Request PHP version upgrades
- Ask about server configuration
Community Forums:
- Search for similar issues
- Ask questions with details

Information to Provide

When seeking help, include:

PHP version
Server type (Apache/Nginx)
Error messages
Error logs
Steps to reproduce
What you've tried

Prevention Tips

Before Installation

Verify Requirements:
- Check PHP version
- Verify extensions
- Test database connection
Backup:
- Backup existing site (if upgrading)
- Backup database
- Document current configuration

During Installation

Follow Steps Carefully:
- Don't skip steps
- Verify each step completes
- Note any warnings
Test as You Go:
- Test database connection
- Verify file permissions
- Check error logs

After Installation

Test Everything:
- Login functionality
- Admin panel access
- Frontend display
- Key features
Monitor Logs:
- Check for errors
- Review warnings
- Address issues promptly

Quick Reference

Common Commands

bash

# Check PHP version
php -v

# Check extensions
php -m

# Clear cache
php artisan cache:clear

# Check routes
php artisan route:list

# Test database
php artisan tinker

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

Permission Commands

bash

# Set directory permissions
chmod -R 755 storage bootstrap/cache public

# Set file permissions
find . -type f -exec chmod 644 {} \;

# Set executable
chmod 755 artisan

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

Troubleshooting Installation Issues ​

Table of Contents ​

Common Error Messages ​

"PHP version 8.2.0 or higher required" ​

"Required PHP extension missing" ​

"Directory is not writable" ​

Permission Issues ​

Symptoms ​

Solutions ​

Check Current Permissions ​

Set Correct Permissions ​

Fix Ownership (if needed) ​

cPanel Specific ​

Database Connection Errors ​

"Access denied for user" ​

"Unknown database" ​

"Can't connect to MySQL server" ​

PHP Extension Errors ​

Missing Extension List ​

Installation Commands ​

Verify Extensions ​

500 Internal Server Error ​

Symptoms ​

Solutions ​

Check Error Logs ​

Common Causes ​

Enable Error Display (Temporary) ​

White Screen of Death ​

Symptoms ​

Solutions ​

Step 1: Check Error Logs ​

Step 2: Enable Error Display ​

Step 3: Check Common Issues ​

Step 4: Check PHP Errors ​

Installer Not Loading ​

Symptoms ​

Solutions ​

Check File Structure ​

Check .htaccess ​

Check mod_rewrite ​

Check Routes ​

Try Direct Access ​

Migration Errors ​

Symptoms ​

Solutions ​

Check Database Connection ​

Run Migrations Manually ​

Check Specific Migration ​

Common Migration Issues ​

Check Database ​

Seeder Errors ​

Symptoms ​

Solutions ​

Run Seeders Manually ​

Check Seeder Files ​

Common Seeder Issues ​

Fresh Start ​

General Troubleshooting Steps ​

Step 1: Check Requirements ​

Step 2: Review Logs ​

Step 3: Clear Cache ​

Step 4: Verify Configuration ​

Step 5: Test Database ​

Step 6: Check File Structure ​

Getting Help ​

Before Seeking Help ​

Support Resources ​

Information to Provide ​

Prevention Tips ​

Before Installation ​

During Installation ​

After Installation ​

Quick Reference ​

Common Commands ​

Permission Commands ​

Related Documentation ​

Troubleshooting Installation Issues

Table of Contents

Common Error Messages

"PHP version 8.2.0 or higher required"

"Required PHP extension missing"

"Directory is not writable"

Permission Issues

Symptoms

Solutions

Check Current Permissions

Set Correct Permissions

Fix Ownership (if needed)

cPanel Specific

Database Connection Errors

"Access denied for user"

"Unknown database"

"Can't connect to MySQL server"

PHP Extension Errors

Missing Extension List

Installation Commands

Verify Extensions

500 Internal Server Error

Symptoms

Solutions

Check Error Logs

Common Causes

Enable Error Display (Temporary)

White Screen of Death

Symptoms

Solutions

Step 1: Check Error Logs

Step 2: Enable Error Display

Step 3: Check Common Issues

Step 4: Check PHP Errors

Installer Not Loading

Symptoms

Solutions

Check File Structure

Check .htaccess

Check mod_rewrite

Check Routes

Try Direct Access

Migration Errors

Symptoms

Solutions

Check Database Connection

Run Migrations Manually

Check Specific Migration

Common Migration Issues

Check Database

Seeder Errors

Symptoms

Solutions

Run Seeders Manually

Check Seeder Files

Common Seeder Issues

Fresh Start

General Troubleshooting Steps

Step 1: Check Requirements

Step 2: Review Logs

Step 3: Clear Cache

Step 4: Verify Configuration

Step 5: Test Database

Step 6: Check File Structure

Getting Help

Before Seeking Help

Support Resources

Information to Provide

Prevention Tips

Before Installation

During Installation

After Installation

Quick Reference

Common Commands

Permission Commands

Related Documentation