Troubleshooting

Solutions to common problems and debugging techniques for XOOPS CMS.

---

📋 Quick Diagnosis

Before diving into specific issues, check these common causes:

1. File Permissions - Directories need 755, files need 644
2. PHP Version - Ensure PHP 7.4+ (8.x recommended)
3. Error Logs - Check xoops_data/logs/ and PHP error logs
4. Cache - Clear cache in Admin → System → Maintenance

---

🗂️ Section Contents

Common Issues

• White Screen of Death (WSOD)
• Database Connection Errors
• Permission Denied Errors
• Module Installation Failures
• Template Compilation Errors

FAQ

• Installation FAQ
• Module FAQ
• Theme FAQ
• Performance FAQ

Debugging

• Enabling Debug Mode
• Using Ray Debugger
• Database Query Debugging
• Smarty Template Debugging

---

🚨 Common Issues & Solutions

White Screen of Death (WSOD)

Symptoms: Blank white page, no error message

Solutions:

1. Enable PHP error display temporarily:

   // Add to mainfile.php temporarily
   error_reporting(E_ALL);
   ini_set('display_errors', 1);

2. Check PHP error log:

   tail -f /var/log/php/error.log

3. Common causes:

   • Memory limit exceeded
   • Fatal PHP syntax error
   • Missing required extension

4. Fix memory issues:

   // In mainfile.php or php.ini
   ini_set('memory_limit', '256M');

---

Database Connection Errors

Symptoms: “Unable to connect to database” or similar

Solutions:

1. Verify credentials in mainfile.php:

   define('XOOPS_DB_HOST', 'localhost');
   define('XOOPS_DB_USER', 'your_username');
   define('XOOPS_DB_PASS', 'your_password');
   define('XOOPS_DB_NAME', 'your_database');

2. Test connection manually:

   <?php
   $conn = new mysqli('localhost', 'user', 'pass', 'database');
   if ($conn->connect_error) {
       die("Connection failed: " . $conn->connect_error);
   }
   echo "Connected successfully";

3. Check MySQL service:

   sudo systemctl status mysql
   sudo systemctl restart mysql

4. Verify user permissions:

   GRANT ALL PRIVILEGES ON xoops.* TO 'user'@'localhost';
   FLUSH PRIVILEGES;

---

Permission Denied Errors

Symptoms: Cannot upload files, cannot save settings

Solutions:

1. Set correct permissions:

   # Directories
   find /path/to/xoops -type d -exec chmod 755 {} \;
   
   # Files
   find /path/to/xoops -type f -exec chmod 644 {} \;
   
   # Writable directories
   chmod -R 777 xoops_data/
   chmod -R 777 uploads/

2. Set correct ownership:

   chown -R www-data:www-data /path/to/xoops

3. Check SELinux (CentOS/RHEL):

   # Check status
   sestatus
   
   # Allow httpd to write
   setsebool -P httpd_unified 1

---

Module Installation Failures

Symptoms: Module won’t install, SQL errors

Solutions:

1. Check module requirements:

   • PHP version compatibility
   • Required PHP extensions
   • XOOPS version compatibility

2. Manual SQL installation:

   mysql -u user -p database < modules/mymodule/sql/mysql.sql

3. Clear module cache:

   // In xoops_data/caches/
   rm -rf xoops_cache/*
   rm -rf smarty_cache/*
   rm -rf smarty_compile/*

4. Check xoops_version.php syntax:

   php -l modules/mymodule/xoops_version.php

---

Template Compilation Errors

Symptoms: Smarty errors, template not found

Solutions:

1. Clear Smarty cache:

   rm -rf xoops_data/caches/smarty_cache/*
   rm -rf xoops_data/caches/smarty_compile/*

2. Check template syntax:

   {* Correct *}
   {$variable}
   
   {* Incorrect - missing $ *}
   {variable}

3. Verify template exists:

   ls modules/mymodule/templates/

4. Regenerate templates:

   • Admin → System → Maintenance → Templates → Regenerate

---

🐛 Debugging Techniques

Enable XOOPS Debug Mode

// In mainfile.php
define('XOOPS_DEBUG_LEVEL', 2);

// Levels:
// 0 = Off
// 1 = PHP debug
// 2 = PHP + SQL debug
// 3 = PHP + SQL + Smarty templates

Using Ray Debugger

Ray is an excellent debugging tool for PHP:

// Install via Composer
composer require spatie/ray --dev

// Usage in your code
ray($variable);
ray($object)->expand();
ray()->measure();

// Database queries
ray($sql)->label('Query');

Smarty Debug Console

{* Enable in template *}
{debug}

{* Or in PHP *}
$xoopsTpl->debugging = true;

Database Query Logging

// Enable query logging
$GLOBALS['xoopsDB']->setLogger(new XoopsLogger());

// Get all queries
$queries = $GLOBALS['xoopsLogger']->queries;
foreach ($queries as $query) {
    echo $query['sql'] . " - " . $query['time'] . "s\n";
}

---

❓ Frequently Asked Questions

Installation

Q: Installation wizard shows blank page A: Check PHP error logs, ensure PHP has enough memory, verify file permissions.

Q: Cannot write to mainfile.php during installation A: Set permissions: chmod 666 mainfile.php during installation, then chmod 444 after.

Q: Database tables not created A: Check MySQL user has CREATE TABLE privileges, verify database exists.

Modules

Q: Module admin page is blank A: Clear cache, check module’s admin/menu.php for syntax errors.

Q: Module blocks not showing A: Check block permissions in Admin → Blocks, verify block is assigned to pages.

Q: Module update fails A: Backup database, try manual SQL updates, check version requirements.

Themes

Q: Theme not applying correctly A: Clear Smarty cache, check theme.html exists, verify theme permissions.

Q: Custom CSS not loading A: Check file path, clear browser cache, verify CSS syntax.

Q: Images not displaying A: Check image paths, verify uploads folder permissions.

Performance

Q: Site is very slow A: Enable caching, optimize database, check for slow queries, enable OpCache.

Q: High memory usage A: Increase memory_limit, optimize large queries, implement pagination.

---

🔧 Maintenance Commands

Clear All Caches

clear_cache.sh

#!/bin/bash
rm -rf xoops_data/caches/xoops_cache/*
rm -rf xoops_data/caches/smarty_cache/*
rm -rf xoops_data/caches/smarty_compile/*
echo "Cache cleared!"

Database Optimization

-- Optimize all tables
OPTIMIZE TABLE xoops_config;
OPTIMIZE TABLE xoops_users;
OPTIMIZE TABLE xoops_session;
-- Repeat for other tables

-- Or optimize all at once
mysqlcheck -o -u user -p database

Check File Integrity

# Compare against fresh install
diff -r /path/to/xoops /path/to/fresh-xoops

---

🔗 Related Documentation

• Getting Started
• Security Best Practices
• XOOPS 4.0 Roadmap

---

📚 External Resources

• XOOPS Forums
• GitHub Issues
• PHP Error Reference

---

#xoops #troubleshooting #debugging #faq #errors #solutions