Frequently Asked Questions

Engine

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 shutdown process can complete. Once all of the workflows have reached transaction breaks, the shutdown process will complete.

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:

http://surachartopun.com/2008/08/ora-08102-index-key-not-found-obj.html

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.

Workflows

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).

Scheduling

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.

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):

${RESULT.filename_matches.size()}

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 following setting to the Java options for the JVM where Flux runs:

-Djcifs.smb.client.dfs.disabled=true

Clustering

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 host’s file is configured incorrectly on one or more machines. See Caching below for more information on configuring the host’s 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 a 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.

Caching

Why am I seeing the error message “Unable to lookup remote cache peer <host name>. Removing from peer list.”?

Flux uses standard Java APIs (java.net.InetAddress) 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:

-Xmx512m

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.

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.

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: java.sun.com.

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.

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 support@flux.ly, 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 wrapper.java.classpath.12 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
    wrapper.app.parameter.2=8


    # Argument count for disposing Flux
    wrapper.app.parameter.13=8
  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 “wrapper.app.parameter.1 = server”. The service wrapper takes these app parameters and coverts them into a command line invocation, so the wrapper.app.parameter 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:
    wrapper.app.parameter.1 = server

    wrapper.app.parameter.2 = -cp
    wrapper.app.parameter.3 = config\engine-config.properties
    wrapper.app.parameter.4 = -username
    wrapper.app.parameter.5 = admin
    wrapper.app.parameter.6 = -password
    wrapper.app.parameter.7 = admin
    wrapper.app.parameter.8 = start
    Will be converted into the command line call:
    flux.Main server -cp config\\engine-config.properties -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.