NuCache Internals & Distributed Cache Synchronization in Scaled Environments

If you've worked with Umbraco past a single-server setup, you've probably run into a strange truth: even a "standalone" site is quietly doing distributed cache work in the background. That's NuCache at work, Umbraco's content caching engine, and the system responsible for making sure every server serving your site agrees on what "published" actually means at any given moment.

This becomes a real engineering concern the moment you scale horizontally. Multiple app servers behind a load balancer means multiple independent copies of the content cache, each living in its own process memory. Without a reliable way to keep those copies in sync, editors publish changes on one server and visitors on another server keep seeing the old version. Understanding how NuCache works internally and how Umbraco keeps it consistent across servers is essential once you're running anything beyond a single instance.

This post breaks down what NuCache is doing under the hood, how synchronization works in load-balanced and scaled environments, and where teams typically run into trouble.

What NuCache Actually Does

NuCache replaced Umbraco's older XML-based cache and changed how content is stored and read at runtime.

• It maintains two separate snapshots of your content tree: one for published content (what visitors see) and one for draft content (what editors see in the back office).
• Content isn't kept as one giant in-memory blob. NuCache uses a local, disk-backed structure so it can serve large content trees without loading everything into memory at once.
• Reads are optimized for speed when a page is requested, NuCache resolves it from its local store rather than re-querying the database or re-parsing XML.
• Each application instance (each server, in a load-balanced setup) builds and maintains its own local copy of this cache. Nothing about NuCache itself is "shared" across servers by default.

That last point is the key thing to internalize before talking about scaling: NuCache is inherently per-instance. Synchronization is a separate mechanism layered on top of it.

Why a Single Cache Per Server Becomes a Problem at Scale

In a single-server setup, there's nothing to keep in sync, one process, one cache, done.

• Add a second server, and you now have two independent NuCache instances that don't know about each other.
• An editor publishing a page updates the cache on the server that handled that request, the other server's cache is now stale.
• Without synchronization, visitors could see different content depending purely on which server the load balancer routes them to.
• This isn't a rare edge case, it's the default outcome of running more than one instance without a sync strategy in place.

How Umbraco Keeps Multiple Servers in Sync

Umbraco solves this with a distributed cache instruction system, built around a concept called cache refreshers.

• Whenever content changes - published, unpublished, moved, deleted, Umbraco generates a "cache instruction" describing what changed.
• These instructions are written to a shared table in the database that every server can read from.
• Other servers periodically check that table, pick up instructions they haven't processed yet, and update their own local NuCache accordingly.
• This is why even a single-server Umbraco site technically runs this machinery, Umbraco treats "one process, one domain" as a load-balancing scenario by design, so the sync mechanism is always active, just usually idle.
• Larger or cloud-hosted setups sometimes layer additional sync approaches on top of this, depending on infrastructure, this can mean relying on managed platform tooling instead of the default database-polling approach.

The practical effect: cache consistency across servers is eventual, not instant. There's a small window between a change happening on one server and every other server catching up.

Where Sync Issues Commonly Show Up at Scale

As traffic and server count grow, a few predictable pain points tend to surface.

• Instruction table growth - high-frequency publishing (bulk imports, scheduled publishing, active content teams) can generate a large volume of instructions, adding load to the database and slowing down polling.
• Propagation delay - brief windows where servers disagree on content state, especially noticeable right after a publish during high traffic.
• Cold starts after deploys - when a server restarts or a new instance spins up, it has to rebuild its NuCache from scratch, which can take real time on large content trees.
• Serialization mismatches - inconsistent serializer configuration across servers (a setting that affects how content is stored internally) can cause errors during cache rebuilds rather than just staleness.
• Clock and timing drift - instruction processing relies on servers reading changes in a consistent order; time drift between servers can cause subtle ordering issues.

None of these are catastrophic on their own, but they compound in high-traffic, frequently published environments if left unmanaged.

Best Practices for Cache Sync in Scaled Environments

• Match your sync strategy to your hosting model, self-managed VMs, containers, and managed cloud platforms each handle this differently, and the wrong assumption here causes most of the pain.
• Monitor the cache instruction table size and processing lag as a standard part of ops monitoring, not an afterthought.
• Warm up the cache proactively after deployments instead of letting the first wave of real traffic trigger a slow cold rebuild.
• Keep serializer and cache configuration identical across every server, this is a common and easily avoidable source of rebuild failures.
• Avoid bulk publishing operations during peak traffic windows when propagation delay is most visible to users.
• Keep server clocks synchronized (NTP) to avoid subtle instruction-ordering issues.

Conclusion

NuCache is doing more work than most teams give it credit for, building and maintaining an optimized, per-server snapshot of your content tree, separately for draft and published states. That design is what makes Umbraco fast at a single-server level, but it also means consistency across multiple servers isn't automatic. It's a deliberate system built on database-driven instructions and periodic polling, not real-time replication.

For most teams, this becomes visible the moment they scale past one instance, a publish that "didn't show up," a new server that takes a while to warm up, a database table nobody had been watching that's suddenly under load. Nothing here is bug, it's the behaviour of an eventually consistent system and it's nothing you can't handle once you understand what is really going on.

The teams that don't experience pain here are those that consider cache synchronization as part of their scaling strategy from the outset, not post-mortem.

If you are architecting or troubleshooting a load-balanced or multi-site/instance you can contact us at Arroact, we work on this type of scaled Umbraco infrastructure all the time.