Troubleshooting Guide

Troubleshooting Guide

Installation Issues

PHP Version Too Old

Error: "PHP version 8.0 or higher required"

Solution:

# Check current version
php -v

# Update PHP (Ubuntu/Debian)
sudo apt update
sudo apt install php8.1 php8.1-cli php8.1-fpm

# Update PHP (CentOS/RHEL)
sudo yum install php81 php81-php-cli php81-php-fpm

Missing PHP Extensions

Error: "Required PHP extension missing"

Solution:

# Install required extensions (Ubuntu/Debian)
sudo apt install php8.1-json php8.1-mbstring php8.1-openssl php8.1-fileinfo

# Install required extensions (CentOS/RHEL)
sudo yum install php-json php-mbstring php-openssl php-fileinfo

Permission Denied

Error: "Permission denied" or "Cannot write to directory"

Solution:

# Set ownership (replace www-data with your web server user)
sudo chown -R www-data:www-data /var/www/html
sudo chmod -R 755 /var/www/html
sudo chmod -R 750 /var/www/html/stockage
sudo chmod -R 750 /var/www/html/uploads

Installer Not Loading

Symptoms: Blank page or 404 error

Solution:

1. Check public/index.php exists
2. Verify Apache mod_rewrite is enabled
3. Check Nginx configuration
4. Review PHP error logs: tail -f /var/log/php-errors.log
5. Verify file permissions

Configuration Issues

Settings Not Saving

Symptoms: Changes not persisting

Solution:

# Check file permissions
chmod 600 stockage/json/config.json
chown www-data:www-data stockage/json/config.json

# Check disk space
df -h

# Check error logs
tail -f stockage/logs/error.log

Email Not Sending

Symptoms: Emails not delivered

Check:

1. SMTP settings are correct
2. Credentials are valid
3. Firewall allows SMTP port
4. Test email function works

Solution:

• Verify SMTP host and port
• Check username/password
• Test with telnet: telnet smtp.gmail.com 587
• Review email logs

Timezone Issues

Symptoms: Incorrect timestamps

Solution:

• Use proper timezone identifier: Europe/Paris (not Paris)
• Set in Admin Panel > Settings > General
• Verify PHP timezone: php -i | grep timezone

Performance Issues

Slow Page Loads

Symptoms: Pages load slowly

Check:

1. Cache is enabled
2. Assets are optimized
3. Server resources adequate
4. Database queries optimized

Solution:

# Enable caching
# Admin Panel > Settings > Performance > Enable Cache

# Clear cache
php app/Cli/console.php cache:clear

# Optimize assets
# Admin Panel > Settings > Performance > Asset Optimization

High Memory Usage

Symptoms: PHP memory errors

Solution:

# Increase PHP memory limit (php.ini)
memory_limit = 256M

Database Slow (SQLite)

Symptoms: Slow queries

Solution:

-- Vacuum database
VACUUM;

-- Analyze tables
ANALYZE;

-- Reindex
REINDEX;

User and Permission Issues

Can't Log In

Symptoms: Login fails

Check:

1. Username/password correct
2. Account not banned
3. Email verified (if required)
4. Rate limiting not blocking

Solution:

• Reset password via "Forgot Password"
• Check user status in admin panel
• Review rate limit settings
• Check error logs

Permission Denied

Symptoms: "You don't have permission"

Solution:

1. Check the permissions of the user's group
2. Verify the category's access restrictions
3. Confirm the user is in the expected group
4. Clear cache and test

Can't Create Discussion

Symptoms: "Permission denied" when posting

Check:

1. User has create permission
2. Category allows new discussions
3. Rate limiting not blocking
4. User is not banned

Solution:

• Verify group permissions
• Check category settings
• Review rate limits
• Check user status

Plugin and Theme Issues

Plugin Not Loading

Symptoms: Plugin doesn't activate

Check:

1. Plugin structure is correct
2. plugin.json is valid
3. Plugin class exists
4. Check error logs

Solution:

# Check plugin structure
ls -la plugins/my-plugin/

# Validate plugin.json
cat plugins/my-plugin/plugin.json | jq .

# Check error logs
tail -f stockage/logs/error.log

Theme Not Loading

Symptoms: Theme doesn't apply

Check:

1. Theme directory structure
2. theme.json is valid
3. CSS/JS files exist
4. File permissions

Solution:

• Verify theme structure
• Check theme.json syntax
• Clear browser cache
• Clear Flatboard cache

Plugin Conflicts

Symptoms: Errors after plugin activation

Solution:

1. Deactivate conflicting plugins
2. Check hook priorities
3. Review plugin code
4. Contact plugin developers

Storage Issues

JSON Storage Errors

Symptoms: "Cannot write to file" or data loss

Solution:

# Check permissions
chmod 750 stockage/json/
chmod 644 stockage/json/*.json

# Check disk space
df -h

# Verify file locks
lsof stockage/json/

SQLite Errors

Symptoms: Database errors

Check:

1. pdo_sqlite extension enabled
2. Database file permissions
3. Disk space available
4. Database integrity

Solution:

# Check extension
php -m | grep pdo_sqlite

# Check database
sqlite3 stockage/sqlite/flatboard.db "PRAGMA integrity_check;"

# Repair database
sqlite3 stockage/sqlite/flatboard.db ".recover" | sqlite3 recovered.db

Email Issues

Emails Not Sending

Symptoms: No emails received

Check:

1. SMTP settings correct
2. Credentials valid
3. Firewall allows SMTP
4. Test email works

Solution:

• Verify SMTP configuration
• Test connection: telnet smtp.gmail.com 587
• Check email logs
• Review spam folder

Emails Going to Spam

Symptoms: Emails in spam folder

Solution:

1. Configure SPF records
2. Set up DKIM signing
3. Use reputable SMTP provider
4. Avoid spam trigger words

Security Issues

CSRF Errors

Symptoms: "CSRF token mismatch"

Solution:

• Clear browser cache
• Ensure cookies enabled
• Check session configuration
• Verify HTTPS if using

Rate Limiting Issues

Symptoms: "Too many requests"

Solution:

• Wait for rate limit reset
• Review rate limit settings
• Contact admin if legitimate
• Check for abuse

Getting Help

Check Logs

Always check logs first:

# Error logs
tail -f stockage/logs/error.log

# PHP errors
tail -f stockage/logs/php-errors.log

# Access logs (if available)
tail -f /var/log/apache2/access.log

Enable Debug Mode

Temporarily enable debug mode:

// In config.json or via admin panel
"debug": true

Community Support

• Official Forum: flatboard.org
• GitHub Issues: github.com/Fred89/flatboard
• Documentation: This documentation

Common Error Messages

"Class not found"

Solution: Clear cache and check autoloader

"File not writable"

Solution: Fix file permissions

"Database connection failed"

Solution: Check SQLite extension and permissions

"Plugin incompatible"

Solution: Update plugin or check compatibility

Prevention

Regular Maintenance

• Update Regularly - Keep Flatboard 5 updated
• Backup Regularly - Maintain backups
• Monitor Logs - Review logs regularly
• Test Changes - Test in staging first

Best Practices

• Follow Installation Guide - Follow official guides
• Set Correct Permissions - Use recommended permissions
• Use HTTPS - Always use HTTPS in production
• Keep Updated - Apply security updates promptly

Resources

• Installation Guide - Installation help
• Configuration Guide - Configuration help
• Security Guide - Security issues
• Performance Guide - Performance issues

Last updated: February 23, 2026