Installation Issues

Fix common installation and setup problems with the Perfex CRM SaaS Module.

Module Upload Fails

Problem: The module zip file won't upload through the Perfex admin panel.

Causes & Solutions:

Cause	Solution
File size exceeds PHP upload limit	Increase upload_max_filesize and post_max_size in php.ini to at least 64M
Server timeout during upload	Increase max_execution_time in php.ini to 300
Permissions issue	Check that the modules/ directory is writable (chmod 755)

Alternative: Upload via FTP/SFTP instead:

1. Extract the zip on your computer

2. Upload the extracted folder to your-perfex/modules/

3. Activate via Setup → Modules in the admin panel

---

Module Not Appearing After Upload

Problem: You uploaded the module but it doesn't appear in Setup → Modules.

Solutions:

1. Make sure the folder structure is correct: modules/saas/ (not modules/saas-module/ or modules/saas/saas/)

2. Check that all files were uploaded completely (compare file count)

3. Clear your browser cache and refresh the page

4. Check file permissions: the entire modules/saas/ directory should be readable by the web server

---

MySQL Verification Fails

Problem: Clicking "Click here to verify server settings" shows an error.

Error: "Access denied for user"

Cause: Wrong MySQL username or password.

Fix:

1. Double-check your MySQL credentials

2. If using cPanel, try using your cPanel username and password

3. Test the credentials manually:

mysql -u your_username -p -h localhost
# Enter your password when prompted
# If you can log in, the credentials are correct

Error: "Can't connect to MySQL server"

Cause: MySQL is not running or wrong host/port.

Fix:

1. Check if MySQL is running: sudo systemctl status mysql

2. Verify the host is correct (usually localhost)

3. Verify the port is correct (usually 3306)

4. If MySQL is on a different server, use that server's IP address

Error: "CREATE command denied"

Cause: The MySQL user doesn't have permission to create databases.

Fix:

-- Log in to MySQL as root:
GRANT ALL PRIVILEGES ON *.* TO 'your_username'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

Or in cPanel: Go to MySQL Databases → User Privileges → Check "ALL PRIVILEGES"

---

Blank White Page After Activation

Problem: After activating the module, you see a blank white page.

Solutions:

1. Check PHP error logs: Look at /var/log/apache2/error.log (Apache) or /var/log/nginx/error.log (Nginx)

2. Enable error display temporarily: Add to your .htaccess or index.php:

   ini_set('display_errors', 1);
   error_reporting(E_ALL);

3. Check PHP version: Make sure you're running PHP 7.4 or higher

4. Check memory limit: Set memory_limit = 256M in php.ini

---

Registration Form Not Showing

Problem: The landing page doesn't show a registration form.

Solutions:

1. Make sure you've created at least one plan in SaaS Management → Plans

2. Check that registrations are enabled in SaaS Management → SuperAdmin Settings → Tenants Settings

3. Verify the landing page URL is correct in Landing Page Settings

4. Try selecting a different landing page template

5. Clear your browser cache

---

Emails Not Being Sent

Problem: Welcome emails, verification emails, or invoice emails are not sent.

Solutions:

1. Configure SMTP in Perfex CRM: Go to Setup → Email → Email Settings

2. Recommended SMTP services:

   • Gmail SMTP (free for up to 500 emails/day)

   • SendGrid (free tier: 100 emails/day)

   • Mailgun (free tier: 5,000 emails/month)

3. Test email sending from Setup → Email → Send Test Email

4. Check your spam folder — emails might be landing there

SMTP is crucial! Without SMTP configured, no emails will be sent from your platform — including verification emails, welcome emails, and invoices. Set this up first!

---

Tenant Database Not Created

Problem: Tenant signs up but their database isn't created.

Solutions:

1. Verify MySQL credentials in SaaS Settings (click the verify button)

2. Check if your MySQL user has CREATE DATABASE privilege

3. If on shared hosting, check if you've reached your database limit

4. Check the SaaS Activity Log for error details

5. Check PHP error logs for MySQL-specific errors

---

"Maximum database connections" Error

Problem: Error about too many database connections.

Solutions:

1. Increase MySQL max_connections in my.cnf:

   [mysqld]
   max_connections = 200

2. Restart MySQL: sudo systemctl restart mysql

3. Consider optimizing your server (more RAM) if you have many tenants

Issue resolved? If you're still having problems, check Domain & DNS Issues or contact Support.