Resolving Ignition Module Uninstall Serialization Failures

Which hops does the uninstall request cross before it fails?

The failure below comes from an Ignition 7.7.5 gateway on Ubuntu, uninstalling the SDK example modulecom.inductiveautomation.examples.simpletagprovider. It reproduced on two separate attempts.

The request stops at hop 7. The damage happened earlier, at hop 4. The checks below trace the fault from hop 7 back to hop 4.

Check 1: Did the module's own shutdown() throw?

Reading: in the gateway wrapper log (lines prefixed INFO | jvm 1), find the ModuleManager line just before the ERROR.

In this case the module reported shutdown completed in 6 ms at 16:03:30,605. A clean return fromshutdown() only proves that no exception escaped. It says nothing about what the method did to objects it received from the platform. That gap is why this fault is easy to misread as a gateway bug.

Check 2: What does the serialization failure on ProjectRecord -1 point to?

Reading: the deepest Caused by in the trace. Here it is org.hsqldb.HsqlException: transaction rollback: serialization failure. The JDBC layer wraps it as java.sql.SQLTransactionRollbackException, and simpleorm wraps it again as simpleorm.utils.SException$Jdbc.

The localdb.hsql.DelegatingDataSource frame shows this is the gateway's internal HSQLDB configuration store, not an external database connection. A serialization failure means the engine rolled back the statement because it conflicted with transaction state held by another session. The engine is refusing to serialize two transactions. This is not a missing-table error, a SQL syntax error, or a sign of a corrupt file.

The statement that failed is a single-row read of the global project, which is PROJECTS_ID = -1, reached through getGlobalProject. On a healthy gateway, a read of one configuration row has nothing to conflict with. So something else left the internal database with a transaction open or abandoned.

Here the failure reproduced on two attempts and was only cleared by reinstalling the gateway. That rules out a one-off collision.

Check 3: Is the gateway in Emergency mode?

Reading: open the Licensing page in the Gateway web configuration and read the license state after the failed uninstall.

In this installation, the Licensing page showed Emergency mode active. Uninstalling a tag provider module has no reason to change licensing state. When licensing changes state at the same moment the internal config DB starts rejecting reads, the fault sits in infrastructure that both subsystems share. It is not in the module's own objects.

Check 4: Does shutdown() stop a service the module does not own?

Reading: the module's gateway hook source. Search it for lifecycle calls made on objects obtained from the GatewayContext:

grep -rn "getExecutionManager().shutdown" src/
grep -rnE "context\.get[A-Za-z]+\(\)\.(shutdown|stop|close)\(" src/

In the failing module, shutdown() contained this sequence:

if (context.getExecutionManager() != null) {
    context.getExecutionManager().shutdown();
}
ourProvider.shutdown();

After those ExecutionManager lines were commented out, the uninstall error could no longer be reproduced.

The rule is to find out who owns an object before you close it. The table below separates objects the module may shut down from objects it may only unregister from.

If the search finds nothing, widen it. Look for any stop, close, or shutdown call on a context-supplied reference, including calls made inside helper classes that the hook invokes.

Why does one shutdown() call take down unrelated gateway functions?

context.getExecutionManager() returns the gateway's shared ExecutionManager. It is not a per-module instance. Gateway subsystems and every loaded module register their periodic work with the same manager. They all run on its scheduling threads.

Calling shutdown() on it stops the scheduler for every caller:

• In-flight tasks are interrupted. A task stopped partway through a unit of work can leave an internal-DB transaction open or abandoned.
• Scheduled tasks stop firing. Periodic housekeeping, including the work that keeps licensing state current, no longer runs.
• Later registrations have no working scheduler behind them. Subsystems that re-register work after the module-set change do not get it executed.

The first code path to touch the internal database after this is the ScriptHintsManager rebuild triggered by the module-stopped notification. It reads the global project, runs into the transaction state left behind, and HSQLDB rolls it back with a serialization failure. The operator sees the error as an uninstall failure. The actual fault is that the module shut down the platform's scheduler.

Why does reinstalling the gateway only appear to fix it?

A reinstall restarts the gateway JVM. At startup the platform creates a fresh ExecutionManager, and every subsystem registers its work again. The broken state disappears, but the module still contains the shutdown() call. The next uninstall, or any module restart that runs the hook's shutdown(), reproduces the fault. That is why it happened twice.

To recover a running gateway, restart the gateway service before considering a reinstall. A service restart rebuilds the same in-memory state that the reinstall rebuilt, and it leaves configuration and installed modules alone. Then use the Licensing page to decide the next step:

• If Licensing returns to normal after the restart, the Emergency mode was a side effect of the stopped executor.
• If Emergency mode persists after a clean restart, treat it as a licensing problem independent of this module.

Neither a restart nor a reinstall fixes the module. Only a code change does.

How should the module release its scheduled work?

Commenting out the ExecutionManager shutdown stops the damage, but it only fixes half the problem. The example module registers a value-update task. With the shutdown line removed and nothing put in its place, that task stays registered on the shared manager after uninstall. It keeps firing against a provider that has been shut down, and against classes from a module classloader that is being discarded. The correct change replaces the shutdown with an unregister.

1. At registration in startup(), use a fixed owner string for the module and a fixed name for each task. Keep both as constants so shutdown() can reference exactly the same keys.
2. In shutdown(), unregister the module's tasks first. Use unRegister for each named task, or unRegisterAll for everything registered under the module's owner string. Check the exact method signatures in the ExecutionManager Javadoc for the SDK version you build against.
3. Shut down the module-owned tag provider after its update task is unregistered. This way no task run can write into a provider that is shutting down.
4. If the module needs its own thread pool, create a private executor in startup() and shut down only that instance in shutdown().
5. Delete every getExecutionManager().shutdown() call, including commented-out copies, so no one restores it later.

The same ownership rule applies to every manager the GatewayContext hands out. Register and unregister your own entries, and leave the manager's lifecycle to the gateway.

How do you verify the fix end to end?

1. Restart the gateway service so the test starts with a fresh shared ExecutionManager. Confirm that the Licensing page no longer shows Emergency mode. If it still does, fix licensing before continuing so the result is not ambiguous.
2. Record a baseline. Note one piece of gateway background activity that does not belong to the module, such as another tag provider updating or a scheduled gateway script running. You will check it again after the uninstall.
3. Build the corrected module and install it. Confirm that the simple tag provider's values update, which proves the value-update task is registered and running.
4. Uninstall the module from the Gateway web interface.
5. In the wrapper log, confirm that Shutdown of module "com.inductiveautomation.examples.simpletagprovider" completed and the hook's Gateway module stopped. line both appear. Also confirm there is no ERROR [ModuleManager] Error running "uninstall" operation, no SQLTransactionRollbackException, and no ERROR [ConfirmationPanel$1].
6. Reopen the Licensing page. The license state must match what it was before the uninstall.
7. Confirm the module's task is gone. No log output or tag writes from the module's update task should appear after the uninstall timestamp.
8. Confirm the baseline activity from step 2 is still updating. This shows the shared executor survived.
9. Repeat the full install and uninstall cycle at least twice more, checking steps 5 through 8 each time. The original fault reproduced on two attempts, so a single clean pass does not prove the fix.

FAQ