Troubleshooting

Safe mode #

If the plugin crashes your site, it tries to get out of your way rather than leaving you with an FTP client and a renamed folder.

A shutdown handler is installed before anything else loads, so it is watching while the code it guards is running. It escalates:

Three things make this trustworthy rather than annoying:

• It only counts errors in its own files. Another plugin's fatal never puts this one into safe mode.
• There is a one-minute floor between rungs. One page view fires several PHP requests, so without the floor three strikes could happen in a second and skip safe mode entirely.
• On a network it never deactivates. Deactivating a network-activated plugin takes it off every site; one subsite's problem must not do that. Each subsite goes into safe mode on its own and keeps working without the plugin's features.

Turning it on or off yourself #

define( 'VERGEML_SAFE_MODE', true );  // force safe mode on
define( 'VERGEML_NO_WATCHDOG', true ); // do not install the handler at all

Safe mode keeps your taxonomies registered and turns everything else off, which makes it the right first step when something looks wrong and you do not yet know what.

---

Common problems #

The media toolbar layout is broken on WordPress 7 #

That is the bug in the old plugin. WordPress 7.0 turned the media toolbar into a fixed two-column CSS grid and gave placement to its own two filters only; extra filters had nowhere to go and stacked into a 300-pixel block with every label above the wrong control.

Deactivate Enhanced Media Library. This plugin alone fixes it — repairing that is the reason the fork exists.

A page builder's media popup shows no folder tree #

Check that the builder is on the list in Compatibility and that your user may upload files; the tree is added only for people who can.

If it is one of the fourteen best-effort builders (Compatibility), that is worth reporting — those are wired to each builder's documented hook but have not been clicked through in a browser.

Everything appears twice #

Two folder plugins are active and both register taxonomies against your media library. Deactivate the other one. A notice tells you when the plugin detects a second folder plugin.

The tree is missing folders in another language #

That should not happen — the tree deliberately shows every folder in every language. If you want per-language folders, return false from vergeml_multilingual_shared_folders.

Nonces fail, or "the link you followed has expired" #

Almost always a URL mismatch: WordPress builds URLs from siteurl, so reaching the site by a different hostname than the one configured fails every nonce. Check Settings → General.

Scripts do not load after an update #

Assets are versioned by the plugin version plus each file's modification time, so a changed file is always a new URL. If you still see stale assets, a caching or optimiser plugin is serving them; the plugin ships exclusions so optimisers leave its scripts alone, but they have to be picked up.

The background describe run is slow #

It runs on WP-Cron, which fires when somebody visits the site, so progress tracks traffic. A site with a real system cron runs it every minute regardless. The screen says so rather than pretending otherwise.

"This site says it is a staging environment" #

Describing is refused on any site whose wp_get_environment_type() is not production, so a clone cannot spend your balance. Use demo mode, or:

define( 'VERGEML_AI_ALLOW_NONPROD', true );

The licence stopped being recognised after a migration #

The key is sealed with a value derived from your site's auth salt. Changing salts reads as "no licence". Re-entering the key is the recovery, and that is by design — a copied database should not yield a working licence.

A run stopped and said the licence was not accepted #

The service answered 401 or 403. Either the key is wrong, the licence has lapsed, or this site is not on the licence. Check the account area. The run stops rather than burning the rest of the batch on calls that will fail identically.

A run stopped and said to get credits #

402. Top up and press start again — it resumes where it stopped and nothing was lost.

Some files came back with an error stub #

The service had trouble on those specific files. The run skipped them and carried on. They were refunded — credits are metered before the image is sent and given back on failure, so you pay for descriptions rather than attempts. Run again and only the missing ones are retried.

---

Diagnostics #

The system report #

Settings → Media Utilities → System report prints everything worth pasting into a support request: versions, environment, table state, counts. Read it before you send it — that is why it is shown.

Extend it with the vergeml_system_report filter.

Known issues for your stack #

Pressing Check for known problems on the Get help screen reads a list of known issues from the AI service at ai.vergelabs.nl, keeps it for twelve hours, and shows only the ones matching what you actually have installed. Nothing is fetched until you press the button, and the request carries no key and no counts.

Checking a claim yourself #

The plugin is GPLv2 and the source is public. If you want to verify that something does or does not happen, the files are named throughout these docs — for example core/quarantine.php for "there is no delete", and core/ai.php for "the service URL is hard-coded".

---

Getting help #

• Send a ticket from Get help inside the plugin. It carries your question, your site address, the system report you can see on the screen, and — only if you type one — your email address.
• The issue tracker on GitHub, which is read by the person who maintains the plugin.

If you are stuck and want to keep the site usable while you wait: safe mode keeps your taxonomies and turns off everything else.