Reporting bugs accurately helps us fix issues faster and improve Flatboard for everyone. This guide will show you how to provide the most helpful bug reports possible.

📋 Before You Report

1. Check the Documentation First

Before reporting a bug, please review our documentation:

  • Troubleshooting Guide - Check if your issue is a known problem with a solution
  • Documentation Search - Use the search function to find relevant information
  • Filter by Tags - Use tags like #troubleshooting, #installation, or #configuration to narrow results

2. Search Existing Reports

  • Check if someone has already reported the same issue
  • Browse recent discussions to see if others are experiencing similar problems
  • Read through closed issues to see if a fix already exists

3. Verify It's Actually a Bug

Ask yourself:

  • Does this happen consistently or randomly?
  • Have you followed the documentation correctly?
  • Is this behavior documented as expected?
  • Could this be a configuration issue?

🎯 Essential Information to Include

A good bug report should contain these key elements:

1. Clear Title

Write a concise, descriptive title that summarizes the issue.

Good examples:

  • ✅ "SQLite: Reply count incorrect when creating new discussion"
  • ✅ "Image upload fails with 413 error in ResourceManager"

Poor examples:

  • ❌ "It doesn't work"
  • ❌ "Bug in the forum"
  • ❌ "Help!!!"

2. Environment Information

Provide details about your setup:

MARK
**Flatboard Version:** 5.0.0-rc.2
**PHP Version:** 8.2.10
**Database:** SQLite / Json
**Web Server:** Apache 2.4 / Nginx 1.24
**Operating System:** Ubuntu 22.04 / Windows Server 2022
**Browser:** Chrome 120 / Firefox 121 / Safari 17

3. Steps to Reproduce

Provide clear, numbered steps that anyone can follow to reproduce the issue:

MARK
**Steps to Reproduce:**
1. Go to the registration page
2. Enter username with spaces: "John Doe"
3. Fill in other required fields
4. Click "Register"
5. Observe the error

4. Expected vs. Actual Behavior

Clearly describe what should happen and what actually happens:

MARK
**Expected Behavior:**
The username validation should reject spaces and show an error message.

**Actual Behavior:**
The registration succeeds, but the profile URL becomes broken: 
`/u/John%20Doe` returns a 404 error.

5. Error Messages and Logs

Include any error messages, warnings, or relevant log entries:

MARK
**Error Message:**

Fatal error: Undefined property: SqliteStorage::$pdoin /path/to/SqliteStorage.php on line 245

CODE

**Server Logs:**

[2025-12-23 14:32:15] PHP Warning: Division by zero in DiscussionController.php:156

CODE

6. Screenshots or Videos

Visual evidence is extremely helpful:

  • Screenshot the error message
  • Show the problematic behavior
  • Highlight the relevant area
  • Record a short video for complex issues

7. What You've Already Tried

List troubleshooting steps you've attempted:

  • Cleared cache
  • Tried different browsers
  • Disabled plugins
  • Checked file permissions
  • Reviewed configuration files

📝 Bug Report Template

Here's a complete template you can use:

MARK

## Bug Description
[Brief description of the issue]

## Environment
- **Flatboard Version:** 
- **PHP Version:** 
- **Database:** 
- **Web Server:** 
- **Operating System:** 
- **Browser:** 

## Steps to Reproduce
1. 
2. 
3. 

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happens]

## Error Messages

[Paste error messages here]

CODE

## Screenshots
[Attach screenshots if applicable]

## Additional Context
- Have you modified any core files? 
- Are you using any custom plugins or themes? 
- When did this issue start occurring? 
- Does it happen in a fresh installation? 

## What I've Tried
- [ ] Cleared cache
- [ ] Checked documentation
- [ ] Disabled plugins
- [ ] Tested in different browser
- [ ] Reviewed server logs

⚠ Common Mistakes to Avoid

Don't

  • ❌ Report multiple unrelated bugs in one thread
  • ❌ Use vague descriptions like "it's broken" or "doesn't work"
  • ❌ Post sensitive information (passwords, API keys, personal data)
  • ❌ Demand immediate fixes or be rude
  • ❌ Hijack existing bug reports with different issues
  • ❌ Post the same bug multiple times

Do

  • ✅ Create separate reports for different issues
  • ✅ Be respectful and patient
  • ✅ Update your report if you find new information
  • ✅ Test suggested fixes and provide feedback
  • ✅ Confirm when the bug is resolved

🔍 Types of Issues

Critical Bugs (Report Immediately)

  • Security vulnerabilities
  • Data loss or corruption
  • Complete system failure
  • Authentication bypass

High Priority

  • Major features broken
  • Database errors
  • Performance issues affecting all users

Medium Priority

  • UI/UX problems
  • Inconsistent behavior
  • Minor functionality issues

Low Priority

  • Cosmetic issues
  • Enhancement requests
  • Documentation typos

💡 Tips for Quality Reports

Be Specific

Instead of: "Notifications don't work"
Write: "Email notifications for new replies are not sent when using SQLite database"

Provide Context

Explain what you were trying to accomplish and why the current behavior is problematic.

Include Version Information

Always specify which version you're using. A bug in rc.1 might already be fixed in rc.2.

Test in a Clean Environment

If possible, test if the bug occurs in a fresh installation without custom modifications.

Follow Up

If developers ask for additional information, respond promptly to help resolve the issue faster.

📚 Additional Resources

đŸ€ Contributing Back

Once your bug is fixed:

  • Test the fix and confirm it works
  • Update the bug report with confirmation
  • Thank the developers for their work
  • Consider contributing to documentation or helping others

Remember: good bug reports help everyone. The more precise and detailed your report, the faster we can identify and fix the issue!

Thank you for helping make Flatboard better! 🙏

Edited on Dec 23, 2025 By Fred .