Installation Issues

Overview

This article covers common issues encountered during Flint Engine installation and their solutions.

Database Connection Failed

Symptom: Installation fails with a database connection error.

Solution: Verify database credentials.

• Check DB_HOST, DB_DATABASE, DB_USERNAME, DB_PASSWORD in .env
• Ensure MySQL is running: systemctl status mysql
• Verify the database exists: mysql -u root -p -e "SHOW DATABASES;"
• Check that the user has permissions on the database
• For remote databases, verify the host and port are accessible

Migration Errors

Symptom: php artisan migrate fails with table or column errors.

Solution: Check MySQL version and permissions.

• Ensure MySQL 5.7+ or MariaDB 10.3+ is installed
• Verify the database user has CREATE, ALTER, and DROP privileges
• Check for conflicting existing tables
• Try running php artisan migrate --force

Permission Denied on Files

Symptom: Installation fails with "Permission denied" errors.

Solution: Fix directory permissions.

# Set ownership to web server user
chown -R www-data:www-data /path/to/flint-engine

# Set directory permissions
find /path/to/flint-engine -type d -exec chmod 755 {} \;

# Set file permissions
find /path/to/flint-engine -type f -exec chmod 644 {} \;

# Make storage writable
chmod -R 775 /path/to/flint-engine/storage
chmod -R 775 /path/to/flint-engine/bootstrap/cache

PHP Version Mismatch

Symptom: Installation fails with PHP version errors or missing functions.

Solution: Check and update PHP version.

• Run php -v to check current version
• Flint Engine requires PHP 8.1+ (8.2 recommended)
• Install the required PHP extensions (see Requirements article)
• Update PHP in your server configuration

URL Rewriting Not Working

Symptom: Pages return 404 errors or the admin panel is inaccessible.

Solution: Configure URL rewriting.

• Apache: Ensure mod_rewrite is enabled and .htaccess is in the public directory
• Nginx: Configure the try_files directive in your server block
• Test with a simple route to verify rewriting works

Blank Page After Installation

Symptom: The site loads but shows a blank white page.

Solution: Enable debug mode.

• Set APP_DEBUG=true in .env
• Check the PHP error log for fatal errors
• Common causes: missing extensions, wrong permissions, cache issues
• After fixing, set APP_DEBUG=false for production

Composer Dependency Issues

Symptom: composer install fails with dependency conflicts.

Solution: Clear cache and try again.

# Clear composer cache
composer clear-cache

# Remove vendor directory and reinstall
rm -rf vendor/
composer install

# If still failing, try with no-dev
composer install --no-dev --optimize-autoloader

Missing .env File

Symptom: Application cannot start because of missing environment configuration.

Solution: Create the .env file.

• Copy .env.example to .env
• Generate an app key: php artisan key:generate
• Configure database and mail settings