package.loaded invalidation during Lua 5.1 to 5.4 migration without downtime

Question

The goal is to update module source in a running Lua 5.4 interpreter without stopping the process, by clearing entries in package.loaded and calling require again.
The constraint is that Lua caches compiled modules in package.loaded, and removing an entry only forces the next require to re-execute the file. It does not invalidate closures, coroutines, or already compiled bytecode that captured functions from the previous load. Migration from Lua 5.1 to 5.4 also introduces compatibility boundaries such as removed setfenv and changed load semantics, so the same source may behave differently across versions.
It is unclear whether module reloading through package.loaded is safe for long-running coroutines, or whether zero-downtime migration requires running Lua 5.1 and 5.4 interpreters side by side and switching traffic at the host or proxy level.
Does clearing package.loaded and re-requiring a module leave existing coroutines bound to the old implementation? Can a Lua 5.1 application migrate to Lua 5.4 without downtime using only module-table invalidation, or is side-by-side VM traffic switching necessary?

Tasadduq Burney · Answer

Clearing package.loaded does not invalidate existing references
p>Clearing an entry in package.loaded and calling require again only forces Lua to re-execute the source file upon the next call. It does not invalidate existing closures, coroutines, or variables that have already captured functions from the previous load. If a coroutine is currently executing or holds a reference to a function from the old module, it will continue using the old logic even after the module is 'reloaded.'

Why Lua 5.1 to 5.4 migration requires side-by-side VMs
p>Migrating from Lua 5.1 to 5.4 using only module-table invalidation is not feasible for zero-downtime for several reasons:

Runtime Incompatibility: A single process cannot simultaneously run Lua 5.1 and 5.4 interpreters. The bytecode format and internal structures differ significantly between versions.
  Breaking Changes: Lua 5.4 removed setfenv and changed the semantics of load. A module written for 5.1 may fail or behave unpredictably in a 5.4 environment regardless of how it is loaded.
  State Persistence: Existing coroutines and global states bound to the 5.1 VM cannot be safely 'migrated' into 5.4 memory structures without risk of corruption or logic failures.

Recommended approach for zero-downtime
To achieve zero-downtime migration, you must use a side-by-side VM traffic switching strategy at the host or proxy level:

Deploy a new set of instances running Lua 5.4 alongside the existing 5.1 instances.
  Use a load balancer (like Nginx, HAProxy, or a custom proxy) to route new traffic to the 5.4 instances.
  Handle state migration at the data layer (e.g., database or shared cache) to ensure the 5.4 instances can pick up where the 5.1 instances left off.
  Gradually decommission the 5.1 instances once all active connections have drained.

Diagnostic: Does your application rely heavily on global state or long-running coroutines that must maintain their execution context across the version transition?

package.loaded invalidation during Lua 5.1 to 5.4 migration without downtime

1 answer

Clearing package.loaded does not invalidate existing references

Why Lua 5.1 to 5.4 migration requires side-by-side VMs

Recommended approach for zero-downtime

Your perspective belongs here.

0 question comments