Troubleshooting

This guide covers common installation issues and their solutions.

Permission Errors

"Permission denied" or "Unable to write"

Symptoms:

• Installation fails with permission errors
• Cannot save files or configurations
• Blank page or 500 error

Solution:

# Set proper ownership
# For AlmaLinux/CentOS/RHEL:
sudo chown -R apache:apache /var/www/mumara

# For Ubuntu/Debian:
# sudo chown -R www-data:www-data /var/www/mumara

# Set directory permissions
sudo find /var/www/mumara -type d -exec chmod 755 {} \;

# Set file permissions
sudo find /var/www/mumara -type f -exec chmod 644 {} \;

# Make storage and bootstrap writable
sudo chmod -R 775 /var/www/mumara/storage
sudo chmod -R 775 /var/www/mumara/bootstrap/cache
sudo chmod 777 /var/www/mumara/.env

SELinux Blocking Access (CentOS/RHEL)

Symptoms:

• Permission denied even with correct chmod settings
• Works when SELinux is disabled

Solution:

# Allow web server to write to storage
sudo chcon -R -t httpd_sys_rw_content_t /var/www/mumara/storage
sudo chcon -R -t httpd_sys_rw_content_t /var/www/mumara/bootstrap/cache

# Or set boolean (less secure)
sudo setsebool -P httpd_unified 1

Database Connection Issues

"SQLSTATE[HY000] [2002] Connection refused"

Symptoms:

• Cannot connect to database during installation
• Application shows database connection errors

Checks:

1. Verify MySQL is running:

   sudo systemctl status mysql
   # or
   sudo systemctl status mariadb

2. Test connection manually:

   mysql -u mumara -p -h localhost mumara_campaigns

3. Check credentials in .env:

   cat /var/www/mumara/.env | grep DB_

Solutions:

# Start MySQL if stopped
sudo systemctl start mysql

# If localhost doesn't work, try 127.0.0.1
# In .env, change:
DB_HOST=127.0.0.1

# Check MySQL socket path
mysql_config --socket
# Update .env with socket if needed:
DB_SOCKET=/var/run/mysqld/mysqld.sock

"Access denied for user"

Symptoms:

• Correct password but access denied
• User exists but cannot connect

Solution:

sudo mysql -u root -p

-- Recreate user with proper grants
DROP USER IF EXISTS 'mumara'@'localhost';
CREATE USER 'mumara'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON mumara_campaigns.* TO 'mumara'@'localhost';
FLUSH PRIVILEGES;

"Unknown database"

Symptoms:

• Database doesn't exist error

Solution:

sudo mysql -u root -p

CREATE DATABASE mumara_campaigns CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

500 Internal Server Error

Check Laravel Logs First

tail -100 /var/www/mumara/storage/logs/laravel.log

Common Causes

Missing .env file:

cp /var/www/mumara/.env.example /var/www/mumara/.env
php artisan key:generate

APP_KEY not set:

cd /var/www/mumara
php artisan key:generate

Cache issues:

cd /var/www/mumara
php artisan config:clear
php artisan cache:clear
php artisan view:clear

Check Apache/Nginx Error Logs

Apache (AlmaLinux/CentOS/RHEL):

tail -100 /var/log/httpd/error_log
tail -100 /var/log/httpd/mumara_error.log

Apache (Ubuntu/Debian):

tail -100 /var/log/apache2/error.log
tail -100 /var/log/apache2/mumara_error.log

Nginx:

tail -100 /var/log/nginx/error.log

Blank/White Page

Enable Error Display

Temporarily enable error display to diagnose:

# Edit .env
nano /var/www/mumara/.env

Set:

APP_DEBUG=true
APP_ENV=local

Refresh the page to see the actual error.

Production

Remember to set APP_DEBUG=false in production after debugging.

Check PHP Error Logs

# Find PHP error log location
php -i | grep error_log

# Common locations
tail -100 /var/log/php/error.log
tail -100 /var/log/php8.3-fpm.log

PHP Memory Limit

If the page dies silently, it may be a memory issue:

# Check current limit
php -i | grep memory_limit

# Increase in php.ini
sudo nano /etc/php/8.3/fpm/php.ini
# Set: memory_limit = 512M

sudo systemctl restart php8.3-fpm

License Validation Failed

Check Internet Connectivity

The server must reach Mumara's license server:

# Test connectivity
curl -I https://my.mumara.com

# Check DNS resolution
nslookup my.mumara.com

Firewall Blocking Outbound

# Allow outbound HTTPS (Ubuntu/Debian with UFW)
sudo ufw allow out 443/tcp

# CentOS/RHEL with firewalld
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

License Key Issues

Issue	Solution
Invalid key	Double-check key from purchase email
Expired	Renew at billing.mumara.com
Domain mismatch	Update licensed domain in client area
IP mismatch	Update licensed IP in client area

Cron Not Running

Verify Cron Entry

# AlmaLinux/CentOS/RHEL (apache user):
sudo crontab -l -u apache

# Ubuntu/Debian (www-data user):
# sudo crontab -l -u www-data

Should show:

* * * * * cd /var/www/mumara && php artisan schedule:run >> /dev/null 2>&1

Test Manually

cd /var/www/mumara

# AlmaLinux/CentOS/RHEL:
sudo -u apache php artisan schedule:run

# Ubuntu/Debian:
# sudo -u www-data php artisan schedule:run

Check Cron Service

# Check if cron is running
sudo systemctl status cron
# or
sudo systemctl status crond

# Check cron logs
grep CRON /var/log/syslog
# or
tail -100 /var/log/cron

Common Cron Issues

Path issues:

# Use full paths in crontab
* * * * * cd /var/www/mumara && /usr/bin/php artisan schedule:run >> /dev/null 2>&1

Environment issues:

# Add environment to crontab
SHELL=/bin/bash
PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
* * * * * cd /var/www/mumara && php artisan schedule:run >> /dev/null 2>&1

Queue Workers Not Processing

Verify Queue Driver Setting

First, check that your queue driver is correctly configured:

1. Navigate to Settings → Application Settings → General
2. Verify the Queue Driver matches your setup:
   • Supervisor - If using Supervisor workers
   • Cronjob - If using cron-based processing
   • Realtime - Only for very small usage (not recommended)

Common Mistake

If you have Supervisor configured but the Queue Driver is set to Cronjob or Realtime, the Supervisor workers will run but jobs won't be dispatched to them. Make sure to set Queue Driver to Supervisor.

Check Supervisor Status

sudo supervisorctl status mumara-worker:*

Common Supervisor Issues

Workers not started:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start mumara-worker:*

Configuration errors:

# Test configuration
sudo supervisord -c /etc/supervisor/supervisord.conf -n

View worker logs:

tail -100 /var/www/mumara/storage/logs/worker.log

Restart Workers After Code Changes

sudo supervisorctl restart mumara-worker:*

Queue Connection Issues

If using Redis:

# Check Redis is running
sudo systemctl status redis

# Test Redis connection
redis-cli ping
# Should return: PONG

Web Installer Issues

Installer Redirects to Homepage

.htaccess not working (Apache):

AlmaLinux/CentOS/RHEL:

# Ensure AllowOverride is set in your virtual host config
sudo nano /etc/httpd/conf.d/mumara.conf
# Add: AllowOverride All

sudo systemctl reload httpd

Ubuntu/Debian:

# Enable mod_rewrite
sudo a2enmod rewrite

# Ensure AllowOverride is set
sudo nano /etc/apache2/sites-available/mumara.conf
# Add: AllowOverride All

sudo systemctl reload apache2

Requirements Check Fails

Missing PHP extensions:

# List installed extensions
php -m

# Install missing extensions (Ubuntu)
sudo apt install php8.3-{extension-name}

# Restart PHP-FPM
sudo systemctl restart php8.3-fpm

Check specific extension:

php -m | grep -i imap
php -m | grep -i curl

Cannot Write to Folders

See Permission Errors section above.

mod_rewrite Issues (Apache)

Check if Enabled

# AlmaLinux/CentOS/RHEL:
httpd -M | grep rewrite

# Ubuntu/Debian:
# apache2ctl -M | grep rewrite

Enable mod_rewrite

AlmaLinux/CentOS/RHEL: mod_rewrite is typically enabled by default. If not, ensure it's loaded in /etc/httpd/conf.modules.d/00-base.conf:

LoadModule rewrite_module modules/mod_rewrite.so

Then restart Apache:

sudo systemctl restart httpd

Ubuntu/Debian:

sudo a2enmod rewrite
sudo systemctl restart apache2

Verify .htaccess is Read

In your Apache virtual host config, ensure AllowOverride All is set:

<Directory /var/www/mumara/public>
    AllowOverride All
</Directory>

PHP-FPM Issues (Nginx)

502 Bad Gateway

Check PHP-FPM is running:

sudo systemctl status php8.3-fpm

Verify socket path:

ls -la /var/run/php/

Match socket in nginx config:

fastcgi_pass unix:/var/run/php/php8.3-fpm.sock;

504 Gateway Timeout

Increase timeout values:

Nginx:

location ~ \.php$ {
    fastcgi_read_timeout 300;
    # ... other settings
}

PHP-FPM:

; In pool config
request_terminate_timeout = 300

Getting Help

If you've tried these solutions and still have issues:

1. Check logs - Always include relevant log entries
2. Document steps - List what you've already tried
3. System info - Include OS, PHP version, web server

Log Locations

Log	AlmaLinux/CentOS/RHEL	Ubuntu/Debian
Laravel	/var/www/mumara/storage/logs/laravel.log	/var/www/mumara/storage/logs/laravel.log
Apache	/var/log/httpd/error_log	/var/log/apache2/error.log
Nginx	/var/log/nginx/error.log	/var/log/nginx/error.log
PHP	/var/log/php-fpm/error.log	/var/log/php/error.log
MySQL/MariaDB	/var/log/mariadb/mariadb.log	/var/log/mysql/error.log
Supervisor	/var/log/supervisor/	/var/log/supervisor/

Contact Support

For license or product-specific issues, contact Mumara support at billing.mumara.com.