Resolving system.mongodb Not Found in Ignition 8.1 Scripts

The MongoDB Connector registers its system.mongodb functions only in the Gateway and Perspective scripting scopes. The Designer Script Console and Vision clients run in a different JVM that never receives those functions. Typing dir(system) in the Designer and finding no mongodb entry is expected behavior. It does not mean the module failed to install. The same applies when a project library script raises a module-availability error in the Designer output console: the call was made from client scope. The fix is to route the call to the Gateway.

Is the module actually loaded on the Gateway?

Start with the lowest layer. Before debugging scope, confirm the Gateway has the module loaded and that its build matches the platform. On the installation in question the pairing was:

Identical build stamps mean the module and platform come from the same release, so compatibility is not the issue. The module file sat under C:\Program Files\Inductive Automation\Ignition\user-lib\modules, which is where the Gateway keeps installed modules. Install and upgrade modules through the Gateway web interface, not by copying files by hand, so the Gateway handles the license and certificate acceptance steps.

Check: open Config > Modules. The MongoDB Connector should show state Running, and the Gateway logs should show no faults for it after a restart. If both hold, the Gateway side is healthy. Move up to scope.

Where does the script actually execute?

Ignition script execution has three hosts, and a function exists only in the host where its module registered it. The editor you typed the code in does not decide where it runs. The caller decides.

A project library script has no fixed scope. It is shared code that loads into whichever JVM imports it. If a Vision button or the Script Console calls myLib.readMongo(), that function runs on the engineer's workstation. There, system.mongodb does not exist. Engineers coming from PLC platforms tend to expect code placed in the project to execute on the server. In Ignition, it executes wherever it is called from.

Check: run print 'mongodb' in dir(system) in the Designer Script Console. A result of False is the correct baseline. It proves only that the Designer is client scope.

How do you prove the function exists in Gateway scope?

Put a probe where the Gateway executes it and read the result from the Gateway log, not from the Designer console. A Gateway timer script or a Perspective button both work. The timer needs no UI:

# Project > Gateway Event Scripts > Timer (temporary probe)
logger = system.util.getLogger("MongoScopeProbe")
logger.info("mongodb present in gateway scope: %s" % hasattr(system, "mongodb"))

1. Add the timer script, save the project, and let it fire once.
2. Open the Gateway web interface log viewer and filter on MongoScopeProbe.
3. Confirm the entry reads True.
4. Delete or disable the timer script.

For Perspective, place the same two lines in a button's onActionPerformed event. Trigger the button from a browser session. Perspective scripts run on the Gateway, so the output lands in the Gateway log, not in the browser.

Check: a True in the Gateway log confirms the module is registered. Any remaining failure is a routing problem, not an installation problem.

How does a Vision client or the Designer reach MongoDB?

Send the request to the Gateway and let the Gateway make the MongoDB call. The data path is: client script → system.util.sendRequest over the client/Gateway connection → Gateway message handler → system.mongodb → MongoDB server → result back along the same path.

1. In the Designer, open Gateway Event Scripts > Message and create a handler, for example mongoQuery.
2. Put all system.mongodb calls inside that handler and return a serializable result (dict, list, string, number).
3. From the Vision client or Script Console, call the handler with system.util.sendRequest.

# Gateway message handler "mongoQuery" (runs on Gateway)
def handleMessage(payload):
    logger = system.util.getLogger("MongoBridge")
    logger.info("request received: %s" % payload)
    # place system.mongodb calls here, using values from payload
    return {"mongodbAvailable": hasattr(system, "mongodb")}

# Client side (Vision event or Designer Script Console)
# "MyProject" is a placeholder: use your project name
result = system.util.sendRequest(project="MyProject",
                                 messageHandler="mongoQuery",
                                 payload={"collection": "example"})
print result

Look up the exact function names and argument order for queries and inserts in the MongoDB Connector section of the Ignition user manual for your module version. Keep them inside the handler.

Check: run the client-side call from the Script Console. It should print {'mongodbAvailable': True}, and the MongoBridge entry should appear in the Gateway log.

Which pitfalls push the call back into client scope?

Check: for every script that touches system.mongodb, trace its caller back to its first trigger. Each chain must start in a Gateway event, a tag event, a Perspective event, or a message handler.

How do you verify the full path end to end?

1. In Config > Modules, confirm the MongoDB Connector is Running with a build matching the Gateway.
2. Confirm the Gateway-scope probe logged True, then remove the probe.
3. Replace the hasattr placeholder in the message handler with a real read against a known collection. Log the document count on the Gateway.
4. From a Vision client, not the Designer, trigger the sendRequest call. Confirm the returned data matches a direct query run against the MongoDB server with its own tooling.
5. From a Perspective browser session, run the same read directly in a component event. Confirm identical results and a matching Gateway log entry.

FAQ