Error Handling and Recovery

Five error-handling layers #

GOCSM uses a layered approach to catch and contain snippet errors.

1. Pre-flight syntax validation #

Before any snippet is written to disk, GOCSM validates the full generated code using PHP’s token_get_all() with TOKEN_PARSE. A ParseError here aborts the write entirely — invalid code never reaches disk and the error message is shown in the admin UI.

2. Try/catch around Throwable #

The Loader wraps each generated-file include or eval fallback execution in a try/catch (\Throwable $e) block. This catches \Error, \Exception, TypeError, and any other throwable — everything except true PHP fatals.

3. Shutdown handler #

register_shutdown_function() is used to catch true fatal errors (E_ERROR, E_COMPILE_ERROR, out-of-memory) that bypass try/catch. On shutdown, error_get_last() is checked for fatal error types.

4. Attributing a fatal to a snippet #

GOCSM only disables a snippet when the error points to it directly, because disabling the wrong snippet would be worse than disabling none:

• During loading. While a snippet’s own code is loading, GOCSM records which snippet it is. A fatal at that moment belongs to that snippet.
• Later, in the snippet’s callbacks. Most snippets register actions and filters that run long after they load. If a fatal happens inside a snippet’s generated file, or the error’s stack trace passes through one, GOCSM disables the snippet whose file is closest to the error.

Some fatals cannot be traced to a snippet, and GOCSM leaves them alone:

• A filter callback that returns the wrong kind of value, where the crash then happens later in other code after the snippet has finished.
• A callback from a snippet running through eval fallback, because eval’d code has no file of its own to point to.
• A site with a custom php-error.php or fatal-error-handler.php drop-in that stops PHP before GOCSM’s handler runs.

In those cases, use the error in your PHP error log and, if needed, safe mode to find and deactivate the snippet.

If GOCSM cannot load snippets at all on a request (for example, its database tables are unavailable), the site keeps working without them and an admin notice says that snippets did not load. The details are recorded in the Sync Log.

5. Safe mode #

If none of the above layers can recover (e.g. the fatal happens during compilation before require_once even runs), use the safe mode URL to load WordPress without PHP snippets and deactivate the offending one.

What happens when a snippet errors #

1. The snippet’s status is set to Error, so it stops running from the next request.
2. The error message is stored and shown on the snippet’s edit screen, under its status.
3. An admin notice appears on the next admin page load: “A GOCSM snippet was disabled after an error.”
4. The error is recorded in the Sync Log.

Recovering a broken snippet #

1. Use safe mode if you cannot reach the admin normally.
2. Find the snippet in the list (status will be Error).
3. Click Edit, read the error under the status, and fix the code. Click Save Snippet.
4. Click Activate (on the edit screen, or under the snippet’s name in the list). Activation checks and regenerates the snippet; if the problem is still there, it goes back to Error with the new message.

If the snippet is from a GitHub collection and the error is in upstream code, wait for the author to publish a fix and apply the update through the reconciliation flow.