## How to diagnose a problem and report a bug
URL: https://hub.jkdevstudio.com/knowledge-base/troubleshooting/diagnose-and-report
Updated: 2026-09-06
Summary: Work out whether a problem is cache, environment, a conflict or a real bug, enable the debug log, and send a report support can act on.
Most things that look broken are unfinished rather than broken. Before hunting the cause of a symptom, confirm the basic steps were all completed.
## Check the basics first
- [ ] The environment meets the server requirements
- [ ] WordPress was prepared before the theme went on
- [ ] The theme is installed **and activated**
- [ ] The license is activated
- [ ] The Pro plugin is installed and active, if you expect Pro features
- [ ] Any integrations the feature needs are installed
The most common "nothing works" cases are on that list: a theme installed but never activated, a [child theme](/knowledge-base/hooks-filters/child-themes-and-overrides) active without its parent, or somebody waiting for Pro features without the Pro plugin. None of those is a bug or an environment problem.
## What kind of problem is it
The class decides where to go next and who can actually fix it.
:::deflist
Not a problem, a setting
: The feature exists, and it is switched off or configured somewhere other than where you looked. The cheapest class: it is solved in the settings rather than in a support ticket.
An environment problem
: Hosting, PHP limits, missing extensions, file permissions, blocked outbound requests. The theme only shows the symptom, and only your host can fix it. The sign: red checks in Diagnostics, values that do not match the requirements.
A front end problem
: Visible in the browser. Broken layout, a script not running, old styles. It lives in the browser and in caches rather than on the server. First check: a private window and cleared caches. Second: the browser console.
A server problem
: A white page, a 500, an interrupted import, the "critical error" screen. Nothing is visible in the browser here, because the cause is in the PHP log. This is the one class that cannot be diagnosed at all without a debug log.
A conflict
: The symptom appears only with a particular third party plugin active. The check takes a minute and saves days of correspondence.
A consequence of your own edits
: Code changes, custom snippets, overridden templates.
:::
## The route, cheapest step first
Skipping steps does not save you time: support will ask for the same things anyway.
:::steps
### Hygiene
Clear caches at every level, check the page in a private window, update the theme and Pro plugin to the current versions, and read the changelog. It may already be fixed.
### Diagnostics
Run the built in diagnostics. One click checks the server, WordPress, the theme, plugins and the connection to Hub, and tells you what is wrong. Faster than any manual investigation.
### System Info
Copy the environment snapshot. You need it either way: to compare values against the requirements yourself, and to attach to a ticket.
### The debug log
If the first three found nothing, or the symptom is a server one, turn on WordPress debugging.
:::
System Info and Diagnostics
## Turning on the debug log
This is a mode built into WordPress where errors are written to a file instead of being swallowed silently. It has nothing to do with the theme.
Add three constants to `wp-config.php`, above the line that says to stop editing:
```php title="wp-config.php"
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
```
**The third constant matters on a live site.**
Without `WP_DEBUG_DISPLAY` set to false, PHP errors are printed into the page your visitors are reading, complete with file paths.
The result lands in `wp-content/debug.log`, which you fetch over SFTP or through your host's file manager. If the file never appears, the folder is not writable, and that is a finding in itself.
Reproduce the problem **after** turning it on, not before. Only what happens while the mode is on gets written.
Turn it off when you are done. The log grows, and on a live site it is both extra volume and extra information sitting where it should not.
Your host's control panel usually has PHP logs in their own section, which is the same content by another route.
**The framework log in System Info is not the same file as `debug.log`.**
It records our own events rather than your site's PHP errors, and neither one replaces the other.
PHP errors and the white screen
## What to attach to a ticket
Open this list and walk it before pressing send:
- the copied System Info report, as text or a text file, not a screenshot
- the Diagnostics report, if you have Pro
- the full error from `debug.log`, including the file path and the trace, not a cropped fragment
- steps to reproduce, the page address, what you expected and what happened
- a screenshot or a short screen recording
- whether it still happens with third party plugins deactivated
That last line saves several days on its own.
## About reporting bugs
The message here is thanks rather than apology. You spent your time describing a problem to us, and that is the shortest route to making the theme better for everybody.
Honestly about the scale: a theme with a Pro plugin and integrations is tens of thousands of lines of code, hundreds of settings and external dependencies. Bugs happen in a system that size. We do not hide from that, and a confirmed bug goes into the next available release.
There is a bug report button on our framework admin screens. It opens your account with the request form already filled in and the type set to a bug.
Two boundaries worth naming in your report. If you edited theme or plugin code directly, added snippets, or use custom templates, say so: that is the first thing we check. And if what you have is a design opinion rather than something broken, it belongs in a feature request, where it will not get lost.
Sending a feature request
## Common questions
The debug log stays empty
Either debugging was switched on after the problem happened, or `wp-content` is not writable, or the failure occurs before WordPress loads, and your host's own PHP log covers all three.
Do I have to test with plugins deactivated?
It is the single most useful minute you can spend, because a symptom that disappears with third party plugins off is a conflict rather than a bug, and naming the culprit in the ticket replaces the entire investigation.
My case does not fit any of the six classes
Open a ticket anyway with the attachment list above, since a well described unusual case is genuinely interesting to us and tends to get looked at quickly.