Frequently Asked Questions (FAQ)


  • Why does my engine display the error "flux.EngineException: The Flux engine could not be created. Error details are included below."?
    If the engine is created as an RMI server (that is, the RMI_SERVER or SECURITY_ENABLED configuration option is set to true), then Flux will attempt to create an RMI registry using the port specified by the REGISTRY_PORT configuration option (if you have not set this option, Flux will use the default value of 1099). When this error occurs, the error message typically indicates that Flux was not able to open the specified port.

    There are a few possible causes for this:
    • The port is not available because another application is already using it. If this is the case, change the REGISTRY_PORT value to a different available port.
    • A firewall or intrusion detector is prevent Flux from using that port. Make sure your firewall is configured correctly to allow Flux appropriate access.
  • Why do I see the error java.rmi.UnmarshalException: error unmarshalling arguments; nested exception is: java.lang.ClassNotFoundException <class name> (no security manager: RMI class loader disabled) when I export or look up a flow chart?
    Most often, this error will occur if your flow chart uses a custom complex persistent variable, but the class for the variable is not available on the engine class path (or, sometimes, the client class path). Check to ensure that your engine and client class paths both contain the necessary class to create your complex persistent variable.

    If your class path settings are correct and this error still occurs, it may be that an older version of the complex variable was persisted to the database, and Flux is no longer able to retrieve the variable because the class path has changed or the class is updated. In this case, remove the flow chart from the engine by deleting its entry in the FLUX_READY table, then re-export the flow chart to ensure that the variable is serialized to the database with the most up-to-date version of the class.
  • Why doesn't my engine immediately shut down when I issue the command to stop it?
    If there are any actions executing when you attempt to shut down the engine, Flux must wait for the flow chart to reach a stopping point (transaction break) before the shut down process can complete. Once all of the flow charts have reached transaction breaks, the shut down process will complete.
  • Why am I seeing the error message "Flux Engine threw exception at start flux.EngineException: It is illegal to configure the Flux engine to specify database or data source information when looking up an RMI engine."?
    This can occur for one of two reasons:
    • You have specified the engine configuration option "Host" in the configuration you are using to create the engine. This configuration option should only be used when looking up a Flux engine, and never when creating one (since it is only possible to create an engine on the local host). You can correct this error by removing the "Host" property from your configuration.
    • You are attempting to look up an engine with database or data source configuration options set. These configuration options should only be used when creating an engine, and never when looking up an engine instance (when you look up the engine it will continue to use the database options specified in its own configuration). You can correct this error by removing the database or data source properties from your configuration before using it to look up the engine.
  • Why am I seeing the error message "java.lang.IllegalStateException: UserTransaction.commit or UserTransaction.rollback has been called more times than UserTransaction.begin. Current transaction has been rolled back"?
    This error typically indicates that Flux is using a data source with XA transactions (or container-managed transactions) enabled, but the DATA_SOURCE_USER_TRANSACTIONS configuration option is not enabled on the engine.

    If you are using a data source with XA transactions enabled, the DATA_SOURCE_USER_TRANSACTIONS configuration option must also be enabled for Flux to work correctly.
  • Why am I seeing the error message "java.sql.SQLException: ORA-08102: index key not found, obj# 10398, file 8, block 716 (2)"?
    This error indicates that an index in the database has become corrupted. Typically this error is resolved by rebuilding the index in question, as described in the link below:
  • Why does my engine fail to start up?
    There are two common reasons an engine might fail to start:
    • The license key is invalid or expired. See License Keys for more information on licensing in Flux.
    • The engine is configured to use a database, but the database driver is not available on the class path. For more information on database drivers (including download links) see Configuring Flux to Run with Databases.
  • Why do I see the error "java.rmi.ConnectException: Connection refused to hostwhen I attempt to connect to my engine, even if the engine is running at the expected location?
    Typically, this error would occur in one of two cases:
    • Another application is already using the port number that the Flux engine is bound to. If this is the case, you can either shut down any other applications using the same port as Flux, or configure the engine to use a different REGISTRY_PORT value.
    • A firewall is preventing the client from connecting to the engine. If this is the case, you can either open the port that the Flux engine uses on your firewall, or use one of the firewall traversal methods described in the Flux background section of this documentation.
    • In some cases, when the remote host communicates its address back to the client, it may use a different host name or IP address than the one the client looked it up with. This can cause problems connecting between the client and server and may lead to errors like this one. 

      To correct this, you'll just need to set the Java property "java.rmi.server.hostname" to the host name or IP address that you want the server to return on remote lookups (often, you'll want this to be the same host name / IP address that you plan to use to look up the remote host from a client). This will look like:

      -Djava.rmi.server.hostname=<host name or IP address>

      You can set this wherever the JVM for the Flux engine is configured (if you're starting Flux from the scripts included in the installation, this will be in the setenv script located under the Flux installation directory. Add the java.rmi.server.hostname property to the list of JAVA_OPTS arguments).

Flow Charts

  • Why does my flow chart continue running an action even after I remove / pause / interrupt the flow chart where it is running?
    If Flux is executing an action when you perform one of these operations, it must allow the action to finish running before the operation can be completed. Once the action is finished running, Flux will complete the operation as appropriate. For a pause, this means preventing the next action from running. For an interrupt, Flux will roll back to the last transaction break and begin executing again from there. For a remove, Flux will roll back the transaction, then remove the flow chart from the engine / database.

    This happens because (due to the nature of Java) it is not possible to kill the running thread, so Flux must instead wait for it to complete normally. For some actions that invoke custom code, like the Java action or custom action, you can use the Flux APIs within your code to check whether the thread should quit (for example, return quietly if flowContext.isInterrupted() returns true). For more information about this, see the Javadoc for the flux.Transactable.interrupt() method.
  • Why do I see the exception "You are attempting to modify flow chart "/My/Namespace/FlowChartName", but the modification failed for one of the following reasons: (1) You did not call one of the "getter" methods on the Engine interface to retrieve your flow chart object, modify that flow chart object in place, and then re-submit the modified flow chart by calling Engine.put() or an equivalent method. (2) You followed the procedure in (1), but your flow chart was modified by another thread after it was retrieved from the engine but before it was re-submitted to the engine. In order to avoid losing the changes made by that other thread, this modification attempt has failed."when I attempt to export a flow chart?
    This error occurs when you attempt to export a flow chart, but the same flow chart (or another with the same name and namespace) is already running on the engine and the structure of the new flow chart does not match the running flow chart.

    When you export a flow chart and there is already a copy running on the engine, Flux will attempt to use the new copy of the flow chart (the copy you are exporting) to update the flow chart running on the engine (applying property changes, etc.) If the structures of the flow charts (including names of actions, the number of actions, and paths and number of flows) do not match, then Flux does not know how to update the existing copy of the flow chart and will throw this exception, indicating that the update cannot be completed. In this case, you must remove the existing copy of the flow chart before you can run the new version (or rename the new version to avoid conflict).


  • Why is my flow chart only firing once when I have set a recurring schedule?
    Because Flux uses the flow chart model for workflows, it is only able to schedule triggers or actions for execution when a flow arrives at that trigger or action. This is true even of time-based triggers or actions that run on a recurring schedule – once the trigger or action fires, the next firing cannot be scheduled until a new flow enters the trigger or action, to indicate to Flux that the next run is ready for schedule. Because of this, there are two options to let a trigger or action run on a repeating schedule:
    • Add a flow from the or action going back into itself. This will schedule the next firing immediately after the previous one fires, so that any errors later in the flow chart do not interfere with the next firing.
    • Add a flow into the repeating trigger or action from another trigger action (usually, this means adding a flow from the last trigger or action in the flow chart back to the one that runs on your schedule). This allows you to specify exactly when the next run is scheduled – if an error occurs in an action somewhere in the flow chart (or some other condition that should prevent the next firing from happening), you can use this workflow model to prevent the next scheduled firing until the error can be recovered.

Time Expressions

  • Why do I see the exception "flux.EngineException: The Cron-style Time Expression <expression> could not be satisfied after searching until <date>" when my schedule is evaluated?
    The engine is not able to find any future firings for this time expression. Common causes for this may include:
    • The time expression only allows past dates - for example, dates from a previous month or year.
    • The time expression is searching for dates that are included in a business interval, but the interval itself does not include any future dates.
    • The time expression is searching for dates that are excluded from a business interval but the interval includes all future dates.
    • You are attempting to forecast a certain number of firings, but the time expression does not allow enough future dates (for example, you are attempting to forecast 5 future firings but there are only 4 possible firings for the expression).

Timer Triggers

  • Why does my Timer Trigger fire several times very quickly after missing a number of firings, instead of resuming its normal schedule?
    By default, a Timer Trigger will attempt to make up all of its missed firings. If you do not want the trigger to make up missed firings, or want it to only make up firings within a certain window, you can set the late time window and makeup firing properties to configure how the trigger responds to missed firings.

File Triggers and Actions

  • How can I determine the number of files a file action or trigger found?
    You can use simple variable substitution to find the total number of files found. Just add the following substitution syntax on whichever property of your action or trigger needs to access the number of files (note that this must be used on the action or trigger that immediately follows your file action or trigger):



  • Why do my engines sometimes become unresponsive or stop processing flow charts when I run them in a cluster?
    Although Flux is designed to operate efficiently in a cluster even when clustered engines cannot communicate with each other, you may find that there are times when the engines encounter difficulties because they are not able to locate one another.

    Typically, this occurs because the hosts file is configured incorrectly on one or more machines. See Caching below for more information on configuring the hosts file correctly.
  • Why do I see entries in my FLUX_CLUSTER table listed in the "disposed" state even though I do not have engines running at those locations?
    The FLUX_CLUSTER table is used to track all of the engines that have connected to this database. This allows engines in a cluster to quickly check the status of other engines and make optimizations in scheduling and execution (for example, a "disposed" engine will not be assigned any work).

    Because engines do not have mechanism for determining whether another instance is only offline momentarily or permanently, entries in this table are not automatically removed. If you are confident that an entry in this table will not become active again, it is safe to manually delete the entry from the database.


  • Why am I seeing the error message "Unable to lookup remote cache peer <host name>. Removing from peer list."?
    Flux uses standard Java APIs ( to find host names. For the networked cache, Flux enters the first host name it is able to locate.

    If the other engines in the cluster cannot resolve this host name, the exception above will occur. If this occurs, you must reconfigure the network to allow the engines to resolve the failed host name, or edit the hosts file of the problematic machine to reorder the host names and IP addresses, then restart all engines running on that machine. If using this latter method, you should make sure that the first host name listed is one that the other machines in the cluster can resolve successfully.
    Why do I see the error "java.lang.OutOfMemoryException" when caching is enabled on my engine?
    Typically, this error occurs because the maximum heap size for the JVM is not large enough to accommodate the cache on the engine. The maximum heap size is specified by setting the JVM option "-Xmx", as in:


    If you are using the default cache settings for the engine, the heap size should be at least 512 MB ("-Xmx512m") to accommodate the cache.

    If you are not able to increase the heap size for your JVM, you may also consider tuning the cache configuration to meet your requirements.

Operations Console

  • Why does the web app fail to display my engine and show the error message "Error looking up engine: Connection refused to host"?
    Most commonly, this error will occur if the RMI_SERVER and SECURITY_ENABLED configuration options are both disabled (or not set at all) in your engine configuration. The engine must have one of these configuration options enabled in order to be remotely accessible (which is required for connecting to the engine using the Operations Console). Note that it is an error to enable both of these options: the RMI_SERVER option should only be used if the engine does not have security enabled, since enabling security will automatically make the engine remotely accessible with no further configuration required.

    If the engine has one of these properties enabled and you are still unable to connect using the Operations Console, there may be a firewall (or similar software or hardware) preventing the Operations Console from connecting to the engine. Check that the engine is running on the expected host, and that the configured REGISTRY_PORT and SERVER_NAME are correct and match the information that the Operations Console is expecting. Also check that there is nothing (like a firewall) preventing network access from the Operations Console to the engine.
  • Why doesn't my flow chart appear on the flow charts page of the console after I have exported it?
    Simple flows may execute too quickly for them to appear on the flow chart list, and when a flow chart is finished it will not appear in this list. For testing purposes you may use a Delay Trigger, Manual trigger, or you can set up the flowchart to loop back to the start action.

    If your workflow throws an exception that is not available on the class path, it will not display in the Operations Console. Flux requires access to the Exception Object in order to gather details about the error that the workflow encountered. If your workflow throws any exceptions, you must ensure that they are available on the engine and Operations Console class path in order for Flux to display them correctly.

Desktop Designer

  • Why do the trigger and action icons in the Desktop Designer disappear or appear as generic Flux icons after I have been using the Designer for some time?
    The JVM where the Designer is running has probably run out of heap space and is not able to display the unique icons for each trigger and action. To correct this, shut down the Designer, open the script you use to launch the Designer, and increase the heap space (specific by the "-Xmx" option in the script) to a larger value.

Flux and Java

  • Why am I seeing the error "java.lang.UnsupportedClassVersionError: flux/Main (Unsupported major.minor version <version>)"?
    Your Java version is not supported by this version of Flux. Refer to the Technical Specifications for a complete list of supported Java platforms.

Flux and GCJ

  • Why am I seeing 'Jar: '-u' mode unimplemented'?
    Flux does not support GCJ. If you try to run Flux against GCJ, you will encounter errors. If you are running GCJ, we suggest installing Java 1.5 or 1.4 from the Sun site at:

    If you continue to experience problems with Flux after you have installed Java 1.5 or 1.4, you may need to check your global variables for JAVA_HOME and PATH as there may still be a reference to the GCJ version of Java instead of the Sun version of Java.

    To find out if GCJ is conflicting with another version of Java, run these commands in a shell:

    echo $JAVA_HOME
    echo $PATH

    If GCJ shows up in JAVA_HOME, it should be replaced with the path of your Java 1.5 or 1.4 install. If GCJ shows up in the PATH variable, make sure that the location of Java 1.5 or 1.4 is before the location of GCJ.

Flux Version Incompatibility

  • Why am I seeing the error "java.lang.ClassNotFoundException: fluximpl.icc_Stub (no security manager: RMI class loader disabled)" when I attempt to make API calls or remote connections to the engine OR why am I unable to connect to my engine from the Operations Console?
    Typically, this error occurs because your client is using a different version of the flux.jar than the engine server. Different Flux versions (even maintenance releases in the same minor series, like 7.9.8 and 7.9.9) are not interoperable - a client for a certain version of Flux must use the same version to avoid problems.

    To resolve this error, make sure that the flux.jar file on your client's Java class path matches the version you are using on the server.

Log Messages

  • Why do I see the message "This job was updated by another client thread or Flux engine. Stopping execution of this job for this thread" in my Flux logs?
    This message simply means that one engine was attempting to execute a flow chart, but upon trying to save the flow chart's information to the database, found that either another engine or a Flux client (possibly an Operations Console user or a Java API call) had updated the flow chart in the database while the engine was executing it. Rather than continuing to execute the flow chart, the engine is ceding control of that flow to the other engine or client that has most recently updated it.

    This message is expected to be logged occasionally as a normal part of Flux operation, especially when Flux is running in a cluster. If you are seeing this message very frequently, or you are seeing that this message is occurring and preventing a workflow from running or completing as expected, it may be a sign of an error. If this is the case, send a mail along with a complete copy of the log where the message appears to, where our support team can assist in investigating further.

Windows Services

  • How can I change the JVM settings for Flux when it is running as a Windows service?
    To change JVM settings (such as memory or class path settings) for Flux when it is running as a service in Windows, follow these steps:
    1. Browse to the services/windows directory under your Flux installation directory.
    2. Run the uninstall script for the service you want to update (for the engine, this is uninstall-engine.bat).
    3. Edit the .conf file for the service (for the engine, this would be engine.conf). This file is a standard Java service wrapper and follows typical conventions for the wrapper file.

      If you add an entry to the class path, be sure to update any subsequent index numbers (for example, if you add an item at position 12, then you will need to update the existing item 12 to use position 13 instead, 13 to 14, etc.). The index number is the number at the end of the entry, so, for example, the line is at index 12.

      If you add an app parameter, you will also need to be sure to update subsequent indices as well (if you add a new parameter that uses lines 13 and 14, for example, then you will need to add 2 to each existing index number from 13 to 21). In addition, make sure that you add the same parameters for stopping and starting the engine (stop and start sections are denoted by comments in the .conf file), and that you update the argument counts which look something like this in the configuration:

      # Argument count for starting Flux

      # Argument count for disposing Flux
    4. Finally, run the installation script for your service to re-install with the new settings (for the engine, this will be install-engine.bat).
Was this article helpful?
0 out of 0 found this helpful



Please sign in to leave a comment.