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 user group permissions
2. Verify category permissions
3. Review user-specific overrides
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