Answers to common questions about Divi Doctor, and fixes for problems with features, forms, background videos, the profiler and monitoring. Select a question to see its answer.
General questions
Does Divi Doctor work with Divi 4?
Divi Doctor is built for Divi 5, version 5.15 or later. The bug fixes and features use the Divi 5 builder. With Divi 4 or another theme they are not supported and most have no effect, and the Features and Bug Fixes screens show a Divi 5 is not active on this site notice. Many diagnostics still run on Divi 4, such as the hosting, update and content weight checks, but the Divi 5 checks are skipped. The Legacy Modules tab and its toolbar count are for Divi 5 only.
Will it slow my site down?
- Diagnostics, Page Scan and Site Weight run only when you open their screens.
- Exception Watch runs on every page load, but it only looks at errors as they happen and writes to its log when Divi code raises one.
- The Request Profiler times only your own browser, only while you record.
- Monitoring, once you turn it on, takes a snapshot every couple of hours: it loads your home page and Divi’s shared stylesheet once.
- The Legacy modules count in the toolbar only runs for logged-in administrators, never for visitors.
- Bug fixes and features do nothing until you switch them on. Their front-end files load only on pages that use them.
Does it edit Divi’s files?
No. Fixes and features hook into Divi while pages load and through Divi’s own builder extension points. Turn one off, or deactivate Divi Doctor, and stock Divi is back. Two actions change data Divi has saved, and only when you click them: restoring a revision in Layout History, of a Theme Builder layout or a Divi Library item, and Remove Klaviyo accounts on the Klaviyo feature card, which deletes the Klaviyo accounts saved in Divi’s email settings.
Who can see the Divi Doctor screens?
Administrators: every screen needs the manage_options capability, and so do the Divi Doctor item in the admin bar and the Legacy modules count on the front end. On multisite, only a network (super) admin can start or stop the Request Profiler, because its loader file is shared by every site in the network.
Does the profiler record my visitors?
No. It records only the browser you started it in, for the time you choose (5 to 60 minutes), and stops by itself. Other users and visitors are never recorded. See Request Profiler and Site Weight.
What if a Divi update changes something?
Each feature card in Divi Doctor → Features runs live checks for the parts of Divi it relies on, such as Builder extension point, and several show the Divi version they were built and checked against. After a Divi update, open Features and Bug Fixes, look for rows that are no longer OK, and send one test through each feature you use, such as a test message for the Contact Form features.
Features and bug fixes
I switched a feature on, but nothing changed. Why?
- Divi 5 isn’t active. The Features screen shows a notice at the top if so.
- The feature also needs to be set on the module. Most features add options inside the Visual Builder, and a page only uses them where you set them. The card’s How it works panel says where the options are.
- A page cache is serving the old page. Clear it after switching a feature on.
- Some options must be set on the module itself, not in a preset: Mailchimp, ActiveCampaign and AWeber tags on the Email Optin module, image captions, and the Blog module’s Order By, Order and Ignore Sticky Posts. The card’s Limits say so.
- Some results only show on the live page, not in the builder preview: the Contact Form’s success and error messages, and Gallery captions in the slider layout. A Gallery that takes its images from a custom field shows the images picked by hand in the builder, because the builder can’t know which post will be shown.
- A check row on the feature’s card isn’t OK. Its reason says what’s missing.
A bug fix says “On — waiting for …”. Is it working?
It’s switched on, but it hasn’t recorded a page view yet. Fixes only run on the front end, and they record what they did on a real page view.
- On — waiting for a front-end visit (the FOUC fix): open any page while logged out, or in a private window, then reload Divi Doctor → Bug Fixes. See Check that it works.
- On — waiting for a first view after a cache clear (the header flash fix): it only acts on the first view after Divi clears a page’s CSS. Save a page in the Visual Builder, open it logged out, then reload Bug Fixes. See Check that it works.
A fix rewrites its record at most once an hour unless the result changes, so the row can name an earlier page or time than your latest visit.
The page flash came back after I installed an optimization plugin. Why?
Optimization plugins that move inline styles to the footer, such as delay CSS or defer CSS options, can undo the fix, because they move Divi’s variables back to the end of the page. If the flash returns, exclude Divi’s inline styles from those options or turn them off, clear the page cache, then view the page source logged out: the <style class="et-vb-global-data …"> blocks should be inside the head.
The fix says “On — nothing to move”. What does that mean?
The fix is switched on, but Divi’s footer code for the global variables wasn’t found, and Divi’s own code at the top of the page wasn’t either. Divi renamed it, or another plugin removed it. Nothing is changed in that case; stock Divi behavior applies.
Does the page-flash fix make my CSS files or images faster?
No. It only moves Divi’s global variables so the page is drawn correctly the first time, which stops the jump. It doesn’t speed up slow CSS files or large images. Custom font files you uploaded still benefit from being preloaded.
The fix says “On — not needed on this Divi version”. What does that mean?
Your Divi version prints its global CSS variables at the top of the page itself, so the page flash fix has nothing to move. Divi 5.19.0 and later do. You can switch the fix off. The header flash fix is separate and is still needed on Divi 5.19.0.
Contact Form and Mailchimp
Form entries aren’t being saved. What should I check?
- Save form entries is on in Divi Doctor → Features, under Contact Form module.
- The form itself saves entries. In the Visual Builder, open the Contact Form and check Content → Form Entries → Save Entries. It’s on by default.
- The message passed Divi’s checks. Only submissions that pass Divi’s own validation are saved; a missing required field or a failed captcha or spam check saves nothing.
- The form is a Divi 5 Contact Form module.
- The feature’s card doesn’t show Entries table as Missing. If it does, switch the feature off and on again. If that doesn’t help, ask your host whether the database user may create tables.
An entry is saved even when Divi’s email then fails to send, and the entry records whether the email went out. See Saved form entries.
The Mailchimp signup or confirmation email didn’t happen. Why?
Both run only after Divi’s own email for that submission was sent, so nothing happens on a validation, captcha, spam-check or mail failure. Check the activity log on the feature’s card in Divi Doctor → Features. Common entries:
- Not sent: no Mailchimp list is selected for this form. Pick a list in the form’s Content → Mailchimp settings. There is no default list.
- Not sent: the form’s Mailchimp list is not saved in Divi any more. Pick the list again. After you add a list in Mailchimp, fetch the lists again in an Email Optin module so Divi saves it.
- Skipped: hourly limit reached. See the next question.
- No Mailchimp API key saved in Divi for this account. Connect Mailchimp once in any Email Optin module (Content → Email Account → Add).
Also check:
- With Ask For Consent on, only visitors who tick the checkbox are subscribed. The message is sent either way. The checkbox shows on the live page, not in the builder.
- A new contact shows as pending until they confirm Mailchimp’s opt-in email. Until the form uses Spam Protection → Use A Spam Protection Service, new contacts are always added as pending, whatever the Double Opt-In setting says.
- The confirmation email goes to the field with the ID
email. A form without that field can’t send one. - A mail plugin that replaces WordPress’s mail function without applying its
wp_mailfilter hides Divi’s email from Divi Doctor, so both follow-ups are skipped. - Full guides: Mailchimp for the Contact Form and Email subject, HTML email and confirmation email.
Which limits protect the forms, and what happens when one is reached?
The limits stop a form being used to send mail or signups to other people, or to fill your disk. Mail and Mailchimp limits count per clock hour, and upload limits in fixed 10-minute windows.
| What | Per address | Per visitor | Site-wide |
|---|---|---|---|
| Confirmation emails | 3 an hour | 10 an hour | 30 an hour |
| Mailchimp signups from the Contact Form | 3 an hour | 10 an hour | 60 an hour |
| File uploads | None | 30 files every 10 minutes | 2,000 stored files or 2 GB |
Only files that were actually stored count toward a visitor’s 30, so picking a file of the wrong type or one that’s too big doesn’t use up the limit. Upload tries of any kind have their own limit of 90 in the same 10 minutes.
When a confirmation or Mailchimp limit is reached, Divi’s own email still goes out and the log shows Skipped: hourly limit reached. A visitor who uploads too many files sees Too many uploads. Please try again in a few minutes. When the site-wide upload store is full, visitors see Uploads are not available right now. Please try again later. until the hourly clean-up removes files older than 24 hours.
“Per visitor” uses the visitor’s IP address. If your site is behind a proxy or CDN that doesn’t pass the real address on, all visitors share one address and reach the limit together. A developer can fix this with the ddoc_client_ip filter; see For developers.
Do I need a Mailchimp account for the Contact Form features?
Only for the Mailchimp options. Divi Doctor uses the Mailchimp account you already connected in Divi’s Email Optin module, and your API key stays on the server; it never reaches the browser.
Where are uploaded files stored?
In wp-content/uploads/ddoc-private/contact-uploads/, in a folder that blocks direct web access, with a random folder name for each file. Files are attached to Divi’s email and deleted by an hourly clean-up 24 hours after upload. When Save form entries is on, a copy of each file is kept with its entry in ddoc-private/form-entries/ until you delete the entry; you download it from the entry screen.
Background videos
My YouTube or Vimeo background video doesn’t show. Why?
- YouTube and Vimeo background videos is off in Divi Doctor → Features. Without it the URL field doesn’t appear.
- The link isn’t recognized. Use a normal YouTube or Vimeo video link, such as a youtube.com/watch, youtu.be, Shorts or vimeo.com link. Other links are ignored, and the builder shows This is not a YouTube or Vimeo video link. It will be ignored. under the field.
- The visitor’s device asks for reduced motion, or the browser’s data saver is on. Then no video loads and the background color or image shows instead. This is on purpose.
- The video is private, deleted or doesn’t allow embedding. The player is removed and the background shows instead. Some Vimeo plans and privacy settings block embedding.
- The browser blocked autoplay. The player stays hidden until it actually plays.
- The link was cleared at a smaller breakpoint, which stops the video from that width down.
- A page cache is serving the old page. Clear it.
The video only starts loading after the rest of the page has loaded and once the section is near the screen, so a short delay is normal. The builder preview shows the link for the breakpoint you’re viewing. If an MP4 and a YouTube or Vimeo link are set for the same breakpoint, the YouTube or Vimeo video shows on top and the MP4 still downloads, so clear one of them. See YouTube and Vimeo video backgrounds.
Why does my YouTube background appear a few seconds after the page loads?
YouTube’s player shows its own previous, pause and next buttons for about three seconds each time a video starts to play, and while it is paused. Divi Doctor (2.1.1 and later) shows the video once those buttons are gone, about four seconds after it starts to play, and shows your background color or image in the meantime, also while the video is paused, buffering or starting over. See Why a YouTube video appears a few seconds after it starts.
My Vimeo link is ignored in Doctor for Divi. Why?
Vimeo background videos are part of Divi Doctor Pro. The free plugin plays YouTube links, and the builder shows Vimeo background videos are part of Divi Doctor Pro. This link will be ignored. under the field. See Doctor for Divi (free) and Divi Doctor Pro.
Safe Mode
A page shows an error while Safe Mode is on. What do I do?
Open your site’s address with ?ddoc-safe-mode-exit=1 at the end, in the same browser. That ends Safe Mode in your browser, so plugins and the child theme load again. Visitors are never affected. See Safe Mode controls.
Plugins look inactive on the Plugins screen while Safe Mode is on. Are they off for my visitors?
No. Safe Mode only switches them off for you, in your browser. With the Safe Mode controls enabled, Divi Doctor also keeps them active for everyone else if you activate or deactivate another plugin in the meantime, and they can’t be deleted while they only look inactive.
Diagnostics, profiler and monitoring
Why do some results say they were checked a while ago?
Some checks are slow, so their results are kept for a while. The content weight checks read every post and are kept for 15 minutes; click Check again under that section to run them now. The Reach update API check is kept for 12 hours when it works and 30 minutes when it fails, so a fixed problem clears quickly.
The profiler says “Limited mode”. What does that mean?
Divi Doctor couldn’t write its small loader file to wp-content/mu-plugins, usually because the folder isn’t writable. Recording still works, but load times of plugins that load before Divi Doctor, and the very first database queries, are missing. Ask your host to make that folder writable if you need the full picture.
The cron light in Cron Setup stays red or amber.
- Give it one cron cycle after setting up the job, then reload the page. Or open the address under Verify it works once in your browser.
- Check that the command was pasted exactly, including the token. A wrong token returns
Divi Doctor monitor: bad token. - The WP-CLI method doesn’t call the address, so the light stays red with it.
- Amber means requests arrived before but not recently. Check the job is still active, and that Expected schedule matches how often it runs.
See Cron Setup.
The cron light is green, but no new snapshots appear.
Monitoring is off. A server cron job that calls the address still reaches the site, so the light stays green, but snapshots are only taken while monitoring is on. Opening the address in your browser shows Divi Doctor monitor: reached, but monitoring is off, so no snapshot was taken. Go to Divi Doctor → Monitoring and click Turn monitoring on.
The toolbar shows “Legacy modules: 3”. What does that mean?
Divi ran 3 Divi 4 modules on that page in backwards compatibility mode. Only administrators see this count. Click it to open Divi Doctor → Diagnostics → Legacy Modules with a scan of that page, which shows where each module is, why it’s legacy and what to do. The count also includes the items inside a module, so it can be higher than the number of rows in the scan. See Legacy Modules.
Your data and uninstalling
What happens to my data if I deactivate or delete Divi Doctor?
Deactivating never deletes data. It removes Divi Doctor’s scheduled tasks and the profiler’s loader file. Reactivate and everything is back, including your monitoring setting and cron address.
Deleting the plugin from Plugins → Installed Plugins always removes the scheduled tasks and the loader file. By default it keeps your data, so reinstalling brings everything back: form entries and their files, the error log, monitoring snapshots, profiler recordings, logs and settings.
How do I remove everything Divi Doctor stored?
- Go to Divi Doctor → Settings.
- Under Data, tick Delete all Divi Doctor data when the plugin is deleted and click Save settings.
- Deactivate and delete Divi Doctor from Plugins → Installed Plugins.
This permanently removes Divi Doctor’s tables (form entries, error log, snapshots and profiler recordings), all of its settings and logs, and the uploads/ddoc-private folder with entry files and pending uploads. It also removes the Klaviyo accounts and API keys that the Klaviyo feature saved in Divi’s email settings. On multisite, each site’s own setting decides whether that site’s data is removed. Export any form entries you want to keep first, with Export CSV on the Form Entries screen.
Options you set inside Divi modules, such as a form’s Mailchimp tags or an image caption, are part of your page content, so they stay there. Divi doesn’t use them without Divi Doctor.
For developers
Divi Doctor has these filters and actions:
| Hook | What it does |
|---|---|
ddoc_client_ip | Filter the visitor IP used for rate limits and saved entries. By default it’s REMOTE_ADDR, never a forwarded header. Behind a proxy, return the address from a header your proxy overwrites. If you return a comma-separated list, the last valid address is used. |
ddoc_cf_confirmation_limits | Hourly confirmation email limits: an array with recipient, ip and site (default 3, 10, 30). |
ddoc_cf_mailchimp_limits | Hourly Contact Form Mailchimp limits, same keys (default 3, 10, 60). |
ddoc_cf_upload_rate_limit | Stored uploads per visitor in each 10-minute window (default 30; 0 turns the limit off). Upload tries are limited to three times this number. |
ddoc_cf_upload_pending_limits | Site-wide cap on stored uploads (default 2,000 files or 2 GB). |
ddoc_cf_entries_capability | Capability needed to see, export and delete form entries (default manage_options). It also opens the Form Entries menu for that role. |
ddoc_cf_entry_data, ddoc_cf_entry_saved | Change or skip an entry before it’s saved, and act after it’s saved. |
ddoc_cf_routing_max_addresses | How many addresses a Contact Form CC, BCC or routing rule can hold (default 20). |
ddoc_klaviyo_api_revision | The Klaviyo API revision sent with each Klaviyo request (default 2026-07-15). |
ddoc_tb_revisions_to_keep | How many revisions Theme Builder layouts keep when revisions are switched off site-wide (default 20). |
ddoc_library_revisions_to_keep | How many revisions Divi Library items keep when revisions are switched off site-wide (default 20). |
ddoc_bcm_admin_bar | Return false to hide the Legacy modules toolbar item. Divi Doctor then also stops learning which plugin adds a legacy module. |
ddoc_prof_skip_hooks | Hooks the Request Profiler leaves untimed. |
Example: pass the real visitor address from Cloudflare.
add_filter( 'ddoc_client_ip', function ( $ip ) {
return isset( $_SERVER['HTTP_CF_CONNECTING_IP'] ) ? $_SERVER['HTTP_CF_CONNECTING_IP'] : $ip;
} );