Before You Post a Bug: The Builder Survival Checklist
Every builder eventually reaches the sacred moment:
“I changed nothing… but everything broke.”
This is usually a lie.
Not an evil lie.
A tired lie.
A 2:14am, seven-tabs-open, coffee-gone-cold kind of lie.
This post is a quick checklist to help you work out what broke, what changed, and what to include when asking for help on Fyrbloc.
Step 1: Ask yourself what changed
Before posting, check what happened just before the problem started.
Did you recently:
- Install an extension?
- Update Composer packages?
- Change PHP versions?
- Edit CSS, HTML, JavaScript, or config files?
- Move hosting/server settings?
- Change DNS?
- Enable Cloudflare?
- Change file permissions?
- Clear cache?
- Not clear cache?
- Paste code from somewhere while feeling powerful?
That last one is common.
A useful bug report starts with:
The last thing I changed was:
Example:
The last thing I changed was:
I installed a Flarum extension, cleared cache, then the admin page started showing a blank screen.
That one sentence can save everyone time.
Step 2: Copy the exact error
Do not describe the error like this:
It said something about something not working.
That is technically emotional poetry, not a bug report.
Better:
Error:
Class "FoF\Something\Extension" not found
Or:
Error:
500 Internal Server Error
Or:
Browser console:
Uncaught TypeError: Cannot read properties of undefined
Exact errors matter.
Step 3: Check the boring stuff first
Boring checks fix a shocking number of problems.
Try these before panic-posting:
Browser
- Hard refresh with
CTRL + F5
- Try private/incognito mode
- Disable browser extensions
- Try another browser
Site cache
For Flarum:
php flarum cache:clear
php flarum assets:publish
Server
Check you are in the right folder:
pwd
Check files exist:
ls -lah
Check Flarum info:
php flarum info
Composer
Check package conflicts:
composer why-not flarum/core 2.0.0
Check installed packages:
composer show
Step 4: Tell people your setup
A good help request includes your setup.
Copy this:
Platform/script:
Version:
PHP version:
Server/control panel:
What I changed:
What broke:
Exact error:
What I already tried:
Screenshot/link:
Example:
Platform/script:
Flarum
Version:
2.0.0-rc.5
PHP version:
8.4
Server/control panel:
CloudPanel
What I changed:
Installed a new extension.
What broke:
The discussion list layout looks wrong.
Exact error:
No visible error, but thumbnail images are not showing.
What I already tried:
Cleared cache, published assets, hard refreshed.
Screenshot/link:
Added below.
That is clean.
That is useful.
That deserves help.
Step 5: Add screenshots properly
Screenshots are useful when the problem is visual.
Good screenshot:
- Shows the actual issue
- Includes enough of the page
- Is not cropped into mystery pixels
- Does not expose private info
- Shows desktop/mobile if relevant
Bad screenshot:
A tiny corner of a button with no context.
That creates detective work. Nobody joined Fyrbloc to become Sherlock CSS.
Step 6: Hide private details
Never post secrets.
Remove or blur:
- Passwords
- API keys
- SMTP details
- Database usernames/passwords
- Private tokens
- Customer data
- Server login details
- Anything from
.env that should stay private
Safe example:
DB_DATABASE=fyrbloc
DB_USERNAME=hidden
DB_PASSWORD=hidden
MAIL_PASSWORD=removed
API_KEY=removed
Unsafe example:
Here is my full config.php and database password.
Do not do that. The internet has teeth.
Step 7: Say what result you want
Sometimes the issue is not just “broken.” It is “not doing what I expected.”
Add this:
What I expected:
Example:
What I expected:
The thumbnail should appear as a square image beside the post title.
What happened:
It shows the default avatar instead.
This makes the answer much easier.
Quick bug report template
Copy this when posting in Quick Help:
What I am trying to do:
What happened:
What I expected:
The last thing I changed:
Exact error message:
My setup:
What I already tried:
Screenshot/link:
Private info removed:
Yes
Useful quick commands
For Flarum:
php flarum info
php flarum cache:clear
php flarum assets:publish
php flarum migrate
For permissions:
chown -R user:user .
find . -type d -exec chmod 755 {} \;
find . -type f -exec chmod 644 {} \;
chmod 640 config.php
chmod -R 775 storage public/assets
For checking logs:
tail -n 100 storage/logs/*.log
For checking web server errors:
journalctl -xe
For checking PHP-FPM:
systemctl status php8.4-fpm
Only run commands you understand. If unsure, ask first.
Final checklist before posting
A little blaming is allowed.
Final note
Bugs are not failure.
Bugs are just your project aggressively asking for attention.
Post clearly.
Share context.
Hide secrets.
Fix the thing.
Build. Break. Debug. Fix. Launch.
