🔧 Troubleshooting Guide

Common issues and their solutions for Xiuno BBS 4.0.4

Database Issues

❌ Problem: Database Connection Failed

Error: "Could not connect to database" or "Access denied for user"

✓ Solution:

Check database credentials in conf/conf.php
Verify MySQL is running:

systemctl status mysql
# or
systemctl status mariadb

3. Test database connection manually:

mysql -h 127.0.0.1 -u xiuno -p
# Enter password when prompted

4. Grant proper privileges:

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

❌ Problem: Tables Not Found

Error: "Table 'xiuno.bbs_user' doesn't exist"

✓ Solution:

Import the database schema:

mysql -u xiuno -p xiuno < /path/to/xiuno.sql

Or check if tables were created with wrong prefix. Verify in conf/conf.php:

'prefix' => 'bbs_',  // Must match your table names

Installation & Setup Issues

❌ Problem: White/Blank Page

Symptom: Completely blank white page with no content

✓ Solution:

1. Enable error display temporarily. Edit index.php:

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

2. Check PHP error logs:

# Apache
tail -f /var/log/apache2/error.log

# Nginx
tail -f /var/log/nginx/error.log

3. Common causes:

Wrong PHP version (requires 7.4-8.4)
Missing PHP extensions
Syntax errors in config file

❌ Problem: 500 Internal Server Error

✓ Solution:

1. Check .htaccess syntax:

# Temporarily rename to test
mv .htaccess .htaccess.bak
# If site works, .htaccess has issues

2. Verify mod_rewrite is enabled:

sudo a2enmod rewrite
sudo systemctl restart apache2

3. Check file permissions:

find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;

Permission Issues

❌ Problem: Upload Failed / Directory Not Writable

Error: "Failed to write file to disk" or "Permission denied"

✓ Solution:

1. Set correct ownership:

sudo chown -R www-data:www-data /home/xiuno/public_html/upload
sudo chown -R www-data:www-data /home/xiuno/public_html/tmp
sudo chown -R www-data:www-data /home/xiuno/public_html/log

2. Set proper permissions:

chmod 755 upload/
chmod 755 tmp/
chmod 755 log/

⚠️ Never use 777: Setting 777 permissions is a serious security risk. Always use 755 for directories and 644 for files.

URL & Routing Issues

❌ Problem: 404 Not Found on All Pages

Symptom: Homepage works but all other pages show 404

✓ Solution (Apache):

1. Enable mod_rewrite:

sudo a2enmod rewrite
sudo systemctl restart apache2

2. Update Apache config to allow .htaccess:

<Directory /home/xiuno/public_html>
    AllowOverride All
    Require all granted
</Directory>

✓ Solution (Nginx):

location / {
    try_files $uri $uri/ /forum.php?$query_string;
}

Performance Issues

❌ Problem: Slow Page Loading

✓ Solution:

1. Enable caching (Redis recommended):

'cache' => array(
    'type' => 'redis',
    'host' => '127.0.0.1',
    'port' => 6379,
),

2. Enable Gzip compression:

'gzip_on' => 1,

3. Optimize database:

mysql -u root -p
USE xiuno;
OPTIMIZE TABLE bbs_thread;
OPTIMIZE TABLE bbs_post;
OPTIMIZE TABLE bbs_user;

4. Check slow query log:

tail -f log/slow_query.log

Email/SMTP Issues

❌ Problem: Emails Not Sending

✓ Solution:

1. Test SMTP connection:

telnet smtp.gmail.com 587

2. Enable SMTP debug mode in conf/smtp.conf.php:

'debug' => 1,  // Shows detailed SMTP errors

3. For Gmail, use App Password (not regular password)

4. Check error logs:

tail -f log/php_log

Login & Session Issues

❌ Problem: Can't Login / Session Expires Immediately

✓ Solution:

1. Check session directory permissions:

chmod 755 tmp/session/
chown www-data:www-data tmp/session/

2. Clear session files:

rm -f tmp/session/*

3. Check cookie settings in config:

'siteurl' => 'https://xiuno.wiki',  // Must match actual URL
'sitedomain' => 'xiuno.wiki',       // Without http/https

4. Clear browser cookies and cache

Plugin & Theme Issues

❌ Problem: Plugin Not Working After Installation

✓ Solution:

1. Clear cache:

rm -rf tmp/*

2. Check plugin is enabled in admin panel

3. Verify plugin compatibility with v4.0.4

4. Check for PHP errors in plugin code

Frequently Asked Questions

How do I reset admin password?

Execute this SQL query:

UPDATE bbs_user 
SET password = MD5('newpassword') 
WHERE uid = 1;

How do I change the site domain?

Update in conf/conf.php:

'siteurl' => 'https://newdomain.com',
'sitedomain' => 'newdomain.com',

How do I backup my forum?

# Database backup
mysqldump -u xiuno -p xiuno > xiuno_backup_$(date +%Y%m%d).sql

# Files backup
tar -czf xiuno_files_$(date +%Y%m%d).tar.gz /home/xiuno/public_html/

How do I upgrade Xiuno?

Backup database and files
Download latest version from /downloads/
Replace files (keep conf/conf.php)
Run upgrade script if provided
Clear cache: rm -rf tmp/*

Diagnostic Commands

Check System Information

# PHP version
php -v

# Installed PHP extensions
php -m

# Apache/Nginx status
systemctl status apache2
systemctl status nginx

# MySQL status
systemctl status mysql

# Disk space
df -h

# Memory usage
free -h

Log File Locations

# Xiuno logs
/home/xiuno/public_html/log/php_log
/home/xiuno/public_html/log/error_log

# Apache logs
/var/log/apache2/error.log
/var/log/apache2/access.log

# Nginx logs
/var/log/nginx/error.log
/var/log/nginx/access.log

# MySQL logs
/var/log/mysql/error.log

Still Having Issues?
• Check community forum for similar problems
• Post detailed error messages and logs
• Include PHP version and server environment
• Use xiuno-manage.sh script for automated diagnostics

Emergency Recovery

Site Down? Quick Recovery Steps

# 1. Restore from backup
mysql -u xiuno -p xiuno < latest_backup.sql

# 2. Fix permissions
bash xiuno-manage.sh

# 3. Clear all cache
rm -rf tmp/*

# 4. Restart web server
systemctl restart apache2  # or nginx

# 5. Check error logs
tail -100 /var/log/apache2/error.log

💡 Prevention Tips:
• Backup regularly (daily for database, weekly for files)
• Monitor disk space and memory
• Keep PHP and MySQL updated
• Test plugin/theme updates on staging first
• Enable debug mode only when troubleshooting