Stale cache results in Haxe compilation server

The short answer

The Haxe compilation server (started with --connect or --server-listen) invalidates a cached module when anything in its tracked dependency set changes — the module's own file, the files it imports, and the signatures of types it references. What it does not reliably track is data pulled in at macro-execution time from outside the module graph. If a macro reads an external file (JSON, XML, a directory listing, environment state) and the source file containing the macro call is untouched, the server has no hash change to react to, so it can legitimately reuse the old typed module. That is the most common cause of the stale results you describe.

What actually triggers invalidation

Based on established behavior (Haxe 3.x/4.x; exact internals vary by version, so treat this as a model, not gospel):

• File content changes. The server compares stored file state (hash and/or modification time, depending on version) for every file in a module's dependency set.
• Dependency changes. If module A depends on B and B is re-typed, A is rechecked too.
• Compilation context changes. Different defines, class paths, or HXML flags produce a different compilation context; the server keys cached state on this, so a flag change effectively bypasses the old cache.
• Macro-registered dependencies. Macros can explicitly declare files they depend on via haxe.macro.Context.registerModuleDependency (module-level) or Context.addResource/dependency APIs. Files registered this way are watched for changes and will invalidate the cached module.

Why your macro case goes stale

If your macro does something like sys.io.File.getContent("data/config.json") during typing and you never register that file as a dependency, the server simply doesn't know the module's output depends on it. The source hash is unchanged, so the cached typed module is reused. Restarting the server clears the in-memory cache, which is why that "fixes" it.

The fix for this case

Register every external input your macro reads:

// inside the macro, after reading the file
haxe.macro.Context.registerModuleDependency(
    "my.pack.ModuleName", "data/config.json");

With that in place, touching config.json invalidates the module on the next --connect build — no server restart needed. For runtime-generated files that change outside the compiler's view (codegen outputs, timestamps), there is no built-in watcher; either register the generator's inputs as dependencies or restart the server as part of the codegen step.

How to verify which situation you're in

1. Start the server with verbose output: haxe --server-listen 6000 -v (or --connect 6000 -v on builds) and watch for re-typing messages.
2. Modify only the external resource file and rebuild. If the module is not re-typed, its dependency wasn't registered — that confirms the diagnosis.
3. Add registerModuleDependency and repeat; the module should now invalidate.

One caveat worth flagging: invalidation internals (hash vs. timestamp, context keying) have shifted across Haxe versions, so if behavior differs from the above, note your haxe --version — that detail would change the recommendation.