Child pages
  • FAQ
Skip to end of metadata
Go to start of metadata


Why does my engine display the error "flux.EngineException: The Flux engine could not be created. Error details are included below."?

When the Flux engine starts, it will attempt to bind to the TCP/IP port specified by the ENGINE_PORT configuration settings. 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 ENGINE_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 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 workflow to reach a stopping point (transaction break) before the shut down process can complete. Once all of the workflows have reached transaction breaks, the shutdown process will complete.

Why do my workflows enter the FAILED state after I shut down or restart the engine?

This can happen if the JVM is terminated while workflows are still executing, or haven't reached a transaction break while the engine is disposing.

Most commonly, this would occur if a "quit" or "kill" signal is issued to the JVM before the engine shuts down cleanly, but can also occur if a container or service wrapper times out and destroys the JVM before Flux cleanly exits. To prevent this, avoid manually destroying the JVM while Flux is running, and ensure that any wrapper / container surrounding the Flux process does not contain a timeout that could destroy the JVM prematurely.

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 can't I remove a workflow from the dashboard?

There may be instances where you are unable to remove a workflow from the engine using the Flux Operations Console. In such instances - to force remove the workflow from the Flux Engine - run the following database commands:

Removing a workflow
delete from FLUX_READY where FLOW_CHART_NAME = '/MyFlowChartName';
delete from FLUX_FLOW_CHART where NAME = '/MyFlowChartName';

You can run  the above commands within a Flux Database Action or from the database's command line.

If you use a Flux Database Update Action, do not include the ';' at the end of each statement.

Why does my workflow continue running an action even after I remove / pause / interrupt the workflow 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 workflow 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/Workflow", 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 workflow?

This error occurs when you attempt to export a workflow, but the same workflow (or another with the same name and namespace) is already running on the engine and the structure of the new workflow does not match the running workflow.

When you export a workflow and there is already a copy running on the engine, Flux will attempt to use the new copy of the workflow (the copy you are exporting) to update the workflow running on the engine (applying property changes, etc.) If the structures of the workflows (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 workflow and will throw this exception, indicating that the update cannot be completed. In this case, you must remove the existing copy of the workflow before you can run the new version (or rename the new version to avoid conflict).


Why is my workflow only firing once when I have set a recurring schedule?

Because Flux uses a workflow, it is only able to schedule triggers or actions for execution when execution 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 execution once again 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 workflow 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 workflow 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 workflow (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.

How does Flux select a job and schedule it for execution?

In order to conserve processing power and perform job selection as quickly as possible, Flux makes some optimizations when determining which jobs to run next from the database. As one of these optimizations, Flux uses a simple query to determine the lowest priority value in the database, then performs a select to find all workflows with the same value or lower in the priority (priority values are specified in reverse-order – so a lower value indicates a higher priority).

The way a Flux engine selects a job is as follows:

    • Find LAST_PRIORITY (in this case the minimum value of the EFFECTIVE_PRIORITY in the Flux ready table
    • Then collect 200 candidate flows to execute that are <= to LAST_PRIORITY above
      • select the top 200 rows from FLUX_READY where EFFECTIVE_PRIORITY <= LAST_PRIORITY and LAST_PRIORITY >= 1
      • Otherwise sort by EFFECTIVE_PRIORITY, EXECUTION_TIME and PK, all ASC
    • Flux, row by row, assesses whether or not the workflow can be run based on the concurrency throttles (namespace and cluster_wide) when the engine attempts to claim (also known as seal) the workflow. If it can claim the workflow, the engine claims the workflow for execution on this engine (if networking is disabled) and then spins off as a Flux runner thread for execution. Flux's FlowChartExecutor then executes the workflow.
    • If no concurrency throttles are available to run the workflow in the current row, the engine skips to the next row.
    • If, after iterating through these 200 rows the engine finds nothing it can run, it repeats the process again.

How does Flux handle daylight savings time (DST)?

Flux receives its time zone and system clock information from the underlying JVM. In nearly all cases, the JVM will automatically adjust the system clock when daylight savings time begins and ends. For more information about this, see Timezones and the Java Runtime Environment from Oracle's Java documentation.

Why do I see the exception " The workflow "<workflow>" is running on a secure Flux engine but no Run As User has been specified. Every workflow that runs on a secure Flux engine must run as some user. See the RUN_AS_USER runtime configuration property or the Run As User property on the flux.FlowChart interface for more information."?

On a secured Flux engine, workflows require an associated user – identified by the Run As User property – in order to perform secured operations on the engine.

If the workflow was exported to the engine while security was disabled (or if the SECURITY_ENABLED Engine Configuration property is not specified), it is added to the engine without a Run As User associated. If security is enabled on the engine later, this error will appear.

This error can be resolved by editing the workflow to include a "Run As User" property, or by removing and re-exporting the workflow to the engine.

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 are my file triggers and actions slow when using a UNC host?

Flux attempts to perform domain-based DFS referrals when attempting to resolve UNC hosts / paths, which can cause a long delay when attempting to connect to non-domain environments where such domain-based DFS referrals are undesirable.

In such environments, you can disable DFS domain-based referrals by adding the follow setting to the Java options for the JVM where Flux runs:



Why do my engines sometimes become unresponsive or stop processing workflows 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 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). 

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 ENGINE_PORT is correct and matches 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 workflow appear on the homepage of the console after I have exported it?

Simple flows may execute too quickly for them to appear on the workflow list, and when a workflow 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 workflow to loop back to the start action.

Why does the console flashes when trying to login using "admin" user?

If admin privileges are not correctly set for the user, then it may cause problems when logging in from the console causing it to flash. Check the security privileges for the user in the system.


What happened to Flux Messaging?

Flux Messaging has been removed in favor of using Flow Chart Trigger, Flow Chart Action, and Audit Trail Trigger, which perform and scale much better than Flux Messaging. For users who rely on JMS, JMS remains a strategic fit within Flux. Optionally and at the user's discretion, Flux will continue to integrate with JMS messaging systems.

Desktop Designer

Where did the Desktop Designer go?

A fully functional, feature-complete, browser-based designer is available in the Operations Console in Flux 8.0. Use it to design and edit your workflows. From the web-based designer, you can save workflows directly to the Flux repository.

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.

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 workflow, but upon trying to save the workflow'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 workflow in the database while the engine was executing it. Rather than continuing to execute the workflow, the engine is ceding control of that workflow 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. 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
  3. Finally, restart the service.

How can I change Flux startup settings, like the startup username and password, 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. 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.
  3. Find the line that looks like " = server". The service wrapper takes these app parameters and coverts them into a command line invocation, so the lines specific arguments that will be passed through the command line to Flux.
  4. Edit the wrapper parameters using the Command Line Interface as a guide. For example, the following set of parameters: = server = -cp = config\\ = -username = admin = -password = admin = start 

    Will be converted into the command line call:

    flux.Main server -cp config\\ -username admin -password admin start 

    Add and remove parameters as needed to make the .conf file match the command line invocation you want to use to start Flux.

  5. Finally, restart the service.
  • No labels