Installation FAQs

IMPORTANT: Always back up your database, .env file, and storage/ directory before making any changes to your MailTrixy installation. Incorrect modifications can result in data loss or a broken application.

Remove Public From URL

Apache

To remove /public from the URL on Apache, create a .htaccess file in the root folder and add the following code:


    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]

To also force HTTPS redirection, use:


    RewriteEngine On
    RewriteCond %{HTTPS} !=on
    RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301,NE]
    RewriteRule ^(.*)$ public/$1 [L]

For more details, read the article on Stack Overflow: How to Remove Public Index from URL

Note: This method does not work for localhost and subfolders, only for domains and subdomains.

LiteSpeed

If your server runs LiteSpeed (common on shared hosting with cPanel), the same .htaccess rules above will work. LiteSpeed is fully compatible with Apache rewrite rules. If you encounter issues, ensure the Rewrite module is enabled in your LiteSpeed configuration, or contact your hosting provider for assistance.

Hide or Deny Access to .env

The .env file contains sensitive information such as database credentials, API keys, and mail settings. To prevent direct access to this file, add the following to a .htaccess file in the root folder:

# Disable Directory listing
Options -Indexes
# Block access to .env file

    Order allow,deny
    Deny from all

For Nginx, add the following to your server block:

location ~ /\.env {
    deny all;
    return 404;
}

Debug Mode

Debug mode is helpful for tracking errors during development and troubleshooting, but it should never be left enabled on a live/production site as it exposes sensitive information including database credentials, API keys, and file paths.

To enable debug mode, open your .env file and change:

APP_DEBUG=false    # Change this to true
APP_DEBUG=true

After resolving the issue, always set it back to false:

APP_DEBUG=false

419 Error

A 419 Page Expired error occurs when the CSRF token has expired or is missing. This is a Laravel security feature. Common causes and solutions:

  • Session expired - Refresh the page to get a new CSRF token. You can increase the session lifetime in your .env file: SESSION_LIFETIME=240
  • APP_URL mismatch - Ensure APP_URL in .env matches the actual domain you are accessing (including https://)
  • SESSION_DOMAIN - Verify SESSION_DOMAIN is set correctly in .env
  • Permissions - Ensure storage/framework/sessions directory is writable: chmod -R 775 storage/framework/sessions
  • Cookies blocked - Check that your browser is not blocking cookies from your domain

No Application Encryption Key

If you see the error "No application encryption key has been specified", it means the APP_KEY value in your .env file is missing or empty.

To generate a new application key, run:

php artisan key:generate

This will automatically set the APP_KEY value in your .env file. The key should begin with base64:. After generating, clear the config cache:

php artisan config:cache

.env File Missing

If your .env file is missing, MailTrixy will not be able to connect to the database or function properly. To create it:

  1. Copy the example environment file: 
    cp .env.example .env
  2. Generate a new application key: 
    php artisan key:generate
  3. Open the .env file and configure your database credentials, mail settings, and other required values
  4. Clear the config cache: 
    php artisan config:cache

Note: The .env file may be hidden by your file manager. Enable "Show Hidden Files" in cPanel File Manager or use ls -la via SSH to see it.

Internal Server Error & 500

A 500 Internal Server Error indicates a server-side problem. Follow these steps to diagnose and resolve it:

  1. Enable debug mode temporarily to see the actual error: 
    APP_DEBUG=true
  2. Check the Laravel log file for the full stack trace: 
    tail -f storage/logs/laravel.log
  3. Ensure correct storage permissions: 
    chmod -R 775 storage bootstrap/cache
chown -R www-data:www-data storage bootstrap/cache
  4. Verify .env exists with a valid APP_KEY
  5. Clear all caches: 
    php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
  6. Check .htaccess - Ensure the .htaccess file in the public/ directory is present and not corrupted
  7. Verify PHP version - MailTrixy requires PHP 8.2 or higher
Important: Always set APP_DEBUG=false in production after debugging. Leaving it enabled exposes sensitive information.

MySQL Not Creating Table

If you encounter a SQLSTATE error regarding key length when running migrations, such as "Specified key was too long", add the following to your app/Providers/AppServiceProvider.php in the boot() method:

use Illuminate\Support\Facades\Schema;

public function boot()
{
    Schema::defaultStringLength(191);
}

This issue commonly occurs with older versions of MySQL (below 5.7.7) or MariaDB (below 10.2.2) that use the utf8 character set instead of utf8mb4. After making the change, re-run the migrations:

php artisan migrate

Class 'ZipArchive' Not Found

This error means the PHP zip extension is not installed or enabled on your server. MailTrixy uses ZipArchive for update packages and file exports.

To install it:

  • Ubuntu/Debian: sudo apt-get install php-zip && sudo systemctl restart apache2
  • CentOS/RHEL: sudo yum install php-zip && sudo systemctl restart httpd
  • cPanel: Go to Select PHP Version and enable the zip extension

Verify the extension is loaded: php -m | grep zip

curl_init Error

The error "Call to undefined function curl_init()" means the PHP cURL extension is not installed or enabled. MailTrixy requires cURL for connecting to email providers, AI services, payment gateways, and other external APIs.

To install it:

  • Ubuntu/Debian: sudo apt-get install php-curl && sudo systemctl restart apache2
  • CentOS/RHEL: sudo yum install php-curl && sudo systemctl restart httpd
  • cPanel: Go to Select PHP Version and enable the curl extension

Verify the extension is loaded: php -m | grep curl

404, 403 Errors

404 Not Found

If all routes return 404, the issue is typically with your web server configuration:

  • Apache: Ensure mod_rewrite is enabled and AllowOverride All is set in your virtual host: 
    sudo a2enmod rewrite
sudo systemctl restart apache2
  • Nginx: Add the try_files directive: 
    location / {
    try_files $uri $uri/ /index.php?$query_string;
}
  • Route cache: Regenerate the route cache: php artisan route:cache

403 Forbidden

A 403 error means the server is denying access. Common causes:

  • Incorrect document root - Your web server should point to the public/ directory, not the project root
  • File permissions - Ensure correct ownership and permissions on application files
  • Directory indexing disabled - This is normal and expected. Ensure your web server routes requests through index.php

Payload Too Large

A 413 Payload Too Large error occurs when you try to upload a file or send data that exceeds your server's configured limits. To fix this, update the following settings:

PHP Settings (php.ini)

upload_max_filesize = 64M
post_max_size = 64M
memory_limit = 256M

Nginx (if applicable)

client_max_body_size 64M;

Add this inside the server or http block in your Nginx configuration, then restart Nginx:

sudo systemctl restart nginx

Apache (if applicable)

If using Apache with mod_fcgid, you may also need:

FcgidMaxRequestLen 67108864

exec() Function Disabled

Some features in MailTrixy may require the exec() PHP function (e.g., running Artisan commands programmatically). If you see an error about exec() being disabled:

  • Open your php.ini file and find the disable_functions directive
  • Remove exec from the comma-separated list
  • Restart your web server

On shared hosting with cPanel, go to Select PHP Version → Options and check if exec is in the disabled functions list. If your host does not allow enabling it, contact their support team.

If images, avatars, or uploaded files are not displaying, the storage symbolic link may be missing or broken. MailTrixy requires a symbolic link from public/storage to storage/app/public.

To create the link, run:

php artisan storage:link

If you get an error that the link already exists but images still do not show:

  1. Delete the existing link: 
    rm public/storage
  2. Recreate it: 
    php artisan storage:link

On shared hosting without SSH access: You can manually create the symbolic link by adding the following to a temporary PHP file (e.g., public/symlink.php) and accessing it in your browser:

<?php
symlink('../storage/app/public', './storage');
echo 'Storage link created successfully!';
?>

Important: Delete the symlink.php file immediately after use for security.

Last updated 10/03/2026