Reload or restart

Getting this wrong costs either a pointless 4D restart or, worse, an hour spent debugging code that was never loaded. This page tells you what to do depending on what you changed, and how to know it worked.

The decision

What you changed	What to do
A `.4dm` of the host database — method or class, ORDA included	`POST /_claude/reload`
A `.4dm` of the component (`Components/…`)	Full 4D restart
The structure (`catalog.4DCatalog`)	Full 4D restart
A new class function callable from the web	Reload, then `BSPK_REFRESH_STORAGE`
A template under `Resources/bweb/bspk/*.html`	`BSPK_REFRESH_STORAGE` (templates are cached in `Storage`)
`bspk.js` or another static asset	Nothing — it is served straight from disk
A language file	`BSPK_REFRESH_STORAGE`

Measured on a test database, 4D 21.1, with the Design environment open, and recorded in the component's own source (ClaudeAPI.4dm, reloadProject):

host method changed ........ reloaded (< 4 s)
host class changed ......... reloaded (< 4 s)
host method created hot .... loaded (not found before, callable after)
COMPONENT method ........... NOT reloaded (still v1 after 24 s)
COMPONENT class ............ NOT reloaded

In other words: a changed host method or class is reloaded in under 4 seconds; a host method created while running becomes callable; a component method or class is not reloaded.

The web server stays up during a reload — every request gets an answer.

For a NEW function, the order is not negotiable

Reload then BSPK_REFRESH_STORAGE. Never the refresh alone.

BSPK_REFRESH_STORAGE rescans the class as it currently is in memory. Run on its own after adding a function, it dutifully rewrites the JSON lists — which looks like it worked — but without the new function. Verified: the refresh alone left the call silent; reload then refresh made it callable immediately.

What the refresh actually does:

it reloads all translations;
it rescans callable methods and classes into Storage.vo_AvailableController(ForSelect), the dispatch whitelist;
it reloads the HTML templates;
it re-copies the bweb dependencies.

In compiled mode it re-reads pre-generated JSON instead of scanning — which is why those files must ship with the build.

Worth knowing: Resources/json/AvailableController is a 4D binary format (magic bytes \x01\x02). Searching it for text proves nothing; look at its modification date instead.

Two ways RELOAD PROJECT silently does nothing

It is asynchronous. A call that returns success means the command was issued, not that the code is live.
Without a Design environment open (a merged application), it does nothing at all, and 4D offers no way to detect it.

So never conclude from elapsed time, and never from the HTTP call succeeding. Conclude on a trace only the new code could produce: a log line, a changed value, a new field in a response. Without such a trace, you do not know whether your code is loaded.

Known exception: creating a new host .4dm has proved non-deterministic — a method stayed invisible for about five minutes despite three reloads, then appeared. If the proof fails after a reload, restart rather than insisting.

Restarting properly

Restart through the RESTART 4D command (the host method restart4D, callable via /_claude/exec). Never taskkill /F: a hard kill does not release the web port immediately, and the next startup fails with [10048].

A restart is not always enough on its own either: the component's code has twice needed a second call before it actually served the new version. Same rule — prove it.

Advice: the /_claude routes are development tools. Do not expose them on the Internet.

After a restart, the browser session is gone