Flywheel Compatibility

Flywheel hosting sets wp-config.php to root ownership, so WP Debug Toolkit’s (WPDT) automatic chmod elevation can’t make it writable. As a result, WPDT can’t toggle debug constants or enable Database Monitor’s query logging from within WPDT on Flywheel. Use the Flywheel dashboard to enable WP_DEBUG instead. The Viewer App’s log and query views, the Error Log Viewer, Site Monitor, and Crash Recovery all work normally since none of them write to wp-config.php.

What Flywheel Does

Flywheel auto-generates wp-config.php and sets it to root ownership with 0644 permissions. You cannot edit it via SFTP, and WordPress’s PHP process, which runs as a non-root user, cannot change its permissions or write to it. Flywheel provides its own dashboard controls for settings that would normally go in wp-config.php. For details on Flywheel’s policy, see Flywheel: wp-config.php file edits.

How WPDT Attempts to Toggle Debug Constants

WPDT manages debug constants through two different code paths, and they behave differently on Flywheel.

The admin dashboard and the wp dbtk debug CLI commands both go through WPDT’s Debug Manager, which checks whether wp-config.php is writable and, if not, attempts to make it writable with chmod. On Flywheel, wp-config.php is owned by root while PHP runs as a different user, so the chmod call fails: a process can only change permissions on files it already owns. Debug Manager exits without writing the constant, but it does not always say so. The admin dashboard reports success with a warning attached. The CLI commands report a clean success message with no warning at all. In both cases the constant has not actually changed, regardless of what the response says.

The Viewer App’s Debug Constants panel takes a different path. It does not attempt chmod elevation. It opens wp-config.php directly for writing and, when that fails, reports the failure as a failure. Of the three surfaces, the Viewer App is the only one that tells you accurately that the toggle did not work.

To check the real state of your debug constants on Flywheel, run wp dbtk debug status. This command only reads wp-config.php and is not affected by the write restriction.

This is why Permission Elevation doesn’t resolve the constraint on Flywheel: chmod can only change permissions on files PHP already owns, and wp-config.php on Flywheel is owned by root.

What Works and What Doesn’t

Works without issues on Flywheel:

• Viewer App (log and query views) — operates independently of WordPress; viewing error logs and queries doesn’t touch wp-config.php. Its Debug Constants panel is the exception. See “Does not work” below.
• Error Log Viewer — reads debug.log; does not write to wp-config.php
• Database Monitor (once enabled) — query logs write to wp-content/uploads/, and once query logging is active, viewing and recording queries doesn’t require further wp-config.php writes. Enabling it from within WPDT does require a write, so see “Does not work” below if you haven’t turned it on yet.
• Site Monitor (email notifications) — settings stored in the WordPress database
• Crash Recovery — operates on plugin and theme directories
• Log cleanup — manages log files, not config files
• WP-CLI — all wp dbtk commands work normally on Flywheel except those listed below; wp dbtk debug status reads the current constant values from wp-config.php and is not affected

Does not work on Flywheel:

• WPDT debug constant toggles — the admin dashboard toggles for WP_DEBUG, WP_DEBUG_LOG, and WP_DEBUG_DISPLAY; the CLI commands wp dbtk debug on and wp dbtk debug off; and the Viewer App’s Debug Constants panel (accessible via Settings › Debug Constants tab, or keyboard shortcut K) all attempt to write to wp-config.php, and none of them succeed. They don’t report it the same way: the admin dashboard shows a warning, the CLI reports success with no warning at all, and the Viewer App reports failure. Treat all three as non-functional for changing the constants, regardless of what they report, and use the Flywheel dashboard instead.
• Enabling Database Monitor’s query logging — turning on query logging writes SAVEQUERIES into wp-config.php, which hits the same root-ownership write failure as the debug constant toggles. If query logging was already enabled before the site moved to Flywheel, or SAVEQUERIES was set by another means, logging and log viewing continue to work normally.

Enabling Debug Mode on Flywheel

Use the Flywheel dashboard to enable WP_DEBUG instead of WPDT’s toggle:

1. Log in to your Flywheel dashboard.
2. Select your site.
3. Go to the Advanced tab.
4. Toggle WP_DEBUG on or off.

For step-by-step instructions, see Flywheel: How do I turn on WP_DEBUG?

Once you enable debug mode from the Flywheel dashboard, WPDT reads the debug log and displays it normally. You do not need to configure anything else for it to work.

Related Documentation

Permission Elevation – See why WPDT’s chmod-based elevation works when PHP owns the file, and why Flywheel’s root-owned wp-config.php sits outside what chmod can fix.

Custom Log Paths – If WPDT isn’t automatically picking up your Flywheel debug log, set the path manually here.