FME Form Troubleshooting: Packages

This article discusses some troubleshooting actions that users can take to help resolve issues encountered in FME Form, related to FME packages. Before attempting the troubleshooting guidance outlined in this article, it is recommended that users first have a basic familiarity with the key FME package concepts outlined in our Introduction to FME Packages article.  

This article is for troubleshooting in FME Form. If you are experiencing issues with packages in FME Flow, please see FME Flow Troubleshooting: Packages

Initial Troubleshooting Questions

Here are some initial questions users can ask before proceeding with more in-depth FME package troubleshooting.

Does my system have the recommended minimum FME version and the recommended dependencies for the target FME package and package version of interest?

Each FME package has its own detailed information page on FME Hub. Users can access the information page for an FME package of interest by package version and read about its components, dependencies, and minimum FME requirements.

Before installing an FME package of interest, users should confirm that they are using a version of FME that meets or exceeds the minimum FME version listed for the target FME package. Users should also pay attention to any dependencies listed for the package version of interest and ensure these dependency requirements are met before package installation.

Do I have the system permissions required to install an FME package?

FME packages are add-on components to the FME Platform; they must be downloaded and installed separately from the FME Platform's core applications.

When users choose to install an FME package to a given build of FME Form, the package is, by default, installed at the following system location:

C:\Users\<userName>\AppData\Roaming\Safe Software\FME

Users must have read/write permissions to the above system location in order to install an FME package to a target build of FME Form.  

When exactly does the encountered issue occur?

Identifying exactly when the error(s) with a specific FME package occur(s) is key to determining the next steps in troubleshooting and resolving the encountered issue(s). Does the issue present:

• during package installation?
• while configuring the package canvas object's parameters?
• while running the canvas object?
• after upgrading the FME Form version in use?
• in a newly built workspace, or in an older workspace?

Are there any special instructions for working with FME packages in ArcGIS Data Interoperability?

FME packages install and function in ArcGIS Data Interoperability much the same as they do in FME Form and FME Flow. Users should consult this ArcGIS Data Interoperability Blog post for more details on installing and maintaining FME packages with the ArcGIS Data Interoperability extension.  

Common Issues with FME Packages in FME Form 

The FME package will not install

If issues with FME packages are encountered at package install, users should first verify that their internet connection is stable, particularly if installing the FME package by quick-adding the package's canvas object (transformer or reader/writer) to an FME workspace. Users should also check on whether they are working behind a network firewall or proxy or are subject to antivirus software monitoring; these network components may block the download and/or installation of FME package files.

Users may consider whitelisting certain URLs and/or excluding package install directories in order to download and install FME package files where a firewall, proxy, or antivirus software is involved. Please see the FME Hub section of this article and our FME and Antivirus Software article for more details on URLs and install directories to consider whitelisting or excluding.  

Error Installing FME package due to Process Crash

One common example of an FME package install issue is the Process Crash error. Users may encounter the following messaging in the FME Workbench Translation Log window (or similar) while attempting to install an FME package:

An error occurred while installing package
 'C:\Users\<user>\AppData\Roaming\Safe Software\FME\Packages\<build>-<os>\PackageFiles\safe.<packageName>':
An error occurred while installing Python package with
 'pip install --force-reinstall --no-deps --no-index --find-links
 C:\Users\<user>\AppData\Roaming\Safe Software\FME\Packages\<build>-<os>\PackageFiles\safe.<packageName>\python
 --target C:\Users\<user>\AppData\Roaming\Safe Software\FME\Packages\<build>-<os>\PackageFiles\safe.<packageName>
 --upgrade --no-compile <package name>' : Process crashed 

This Process Crashes error is often triggered by network antivirus software identifying FME’s usage of pip to install the FME package as malicious behavior and subsequently fully blocking the install. Some antivirus software will report this blocking behavior as 'lockdown exploit mitigation.' Adding an exception to the antivirus software will allow FME packages to be successfully installed.  

If the above Process Crash error message is encountered while attempting to install an FME package, and:

• no antivirus software or network firewall is involved; and
• a pre-2022 version of FME Workbench is in use

Users should open their FME Workbench, navigate to Tools --> FME Options --> Translation, and check the settings under the Python Interpreter setting group. If a custom Python interpreter is specified as the Preferred Python Interpreter value, this custom Python interpreter is likely the root cause of the Process Crash error during the FME package installation.

To install FME packages in versions of FME Form pre-2022, a Python interpreter that ships with FME must be used. Users should adjust the Preferred Python Interpreter value to one of the options available in the drop-down list to move away from a custom Python interpreter. Then, try installing the target FME package. This issue with package installs failing on custom Python interpreters was resolved for all versions of FME Form 2022+.

FME package install was successful, but the package's canvas object will not add to the workspace OR doesn't show all expected parameters in the Parameters dialog

Occasionally, users may see a successful install of their target FME package reported in the FME Workbench Translation Log window, but may subsequently encounter issues with adding the package's canvas object to a workspace. If the package's canvas object does appear in the workspace, users may see parameters missing from the canvas object's Parameters dialog.

This unusual behavior may indicate a partial FME package install and may be caused by the user's network firewall, proxy, or antivirus software blocking the installation of some of the FME package's files. The .py files of an FME package are most frequently flagged or blocked in the event of a partial package install. 

If a partial FME package install is suspected, users should fully uninstall the FME package by:

1. Accessing FME Workbench --> Tools --> FME Options --> FME Packages 
2. Highlighting the FME package, which is suspected to have been partially installed
3. Selecting Remove at the bottom-right of the FME Options dialog

Once the package has been removed, users can try reinstalling it by quick-adding the package's canvas object to their workspace and then re-testing.

Alternatively, users could try first downloading the FME package of interest from FME Hub. Once the .fpkg file fully downloads, users can drag and drop it into an FME Workbench canvas to prompt the package installation. Once the package has been installed in this way, users should try adding the package's canvas object to the workspace and confirm it behaves as expected.

Another reason why a package's canvas object does not display all expected parameters in its Parameters dialog is the presence of a .fmx file, of the same file name as the FME package's .fmx file, in the following system location:

C:\Users\<user name>\Documents\FME\Transformers

By default, all of an FME package's components are installed to:

C:\Users\<user name>\AppData\Roaming\Safe Software Inc\FME\Packages\<FME_Build_Number>\

For a package to function correctly in a given build of FME Form, all of the package's components need to be correctly loaded when FME Workbench is initiated. This includes the package canvas object's definition, stored as a .fmx file in:

C:\Users\<user name>\AppData\Roaming\Safe Software Inc\FME\Packages\<FME_Build_Number>\PackageFiles\<package name>\transformers

When FME Workbench is initialized, there is a start-up check done on the ..Documents\FME\Transformers system location; this is where custom transformers typically reside, so FME loads .fmx definitions therein to make them available to use during workspace authoring and running.

If an .fmx file in this Documents location has the same file name as an FME package .fmx file from the AppData location, FME may incorrectly apply the .fmx file from the Documents location when adding and working with the FME package's canvas object during workspace authoring. 

Since the package canvas object's .fmx definition calls other package components by relative file path references, not absolute references, loading the incorrect .fmx for a package canvas object will break all of these relative file path references. This dependency breakage results in some parameters not showing in the package canvas object's Parameters dialog, and may also result in other unexpected package behavior.

Users who see missing parameters from a package canvas object's Parameters dialog should check the Documents system location shown above and verify that a .fmx file of the same name as the FME package's .fmx file is not present therein. If such a .fmx file is currently present in the Documents location, users should rename it, and then restart FME Workbench. Open a blank canvas, add the affected package canvas object, and access its Parameters dialog to confirm that all expected parameters are now present.

FME package install was successful, but translations involving the package's canvas object failed with a "...python function '<function name>' was not found" error

When a translation involving an FME package canvas object fails, and the translation log reports the following error message (or similar)

'The python function '<function name>' was not found. Check your python path & module imports'

users should try uninstalling the related FME package by:

1. Accessing FME Workbench --> Tools --> FME Options --> FME Packages 
2. Highlighting the FME package, which is suspected to have been partially installed
3. Selecting Remove at the  bottom-right of the FME Options dialog

If the FME package will not uninstall following the above steps, it may have been originally installed by a user running FME as an Administrator. The only way to successfully uninstall FME packages that have been installed in this way is to first start up FME Workbench by choosing Run as Administrator. Then, follow the above steps to uninstall the affected FME package.

Once the FME package has been successfully uninstalled, close the elevated instance of FME Workbench and then relaunch it as a non-administrator. Proceed with installing the FME package as a non-administrator by quick-adding the package's canvas object to a workspace or dragging and dropping the package's downloaded .fpkg file into a workspace. 

Reinstalling the FME package as a non-administrator should allow users to run the package's canvas object in translations without encountering the above error.

The web connection built for an FME package canvas object is no longer discoverable in the associated canvas object's Parameters dialog

If users are working with multiple versions of FME Form, including FME Form 2022.x or older, and FME Form 2023 or newer, there is a chance that they may have built FME package web service definitions and follow-on web connections in FME Form 2023+, which are not compatible with FME Form 2022.x or older. 

This incompatibility occurs because FME package canvas objects used in FME Form 2022.x or older will only recognize web connections built using the named web service that shipped with the installed package. In Form 2022.x or older, users were required to directly edit the web service definition that was included with an FME package install but not change the name of the web service in order to build follow-on web connections that would be recognized by the package's canvas object.

As of FME Form 2023.0, package web services can be created using the Create From functionality of the Manage Web Services dialog. When a package's web service is created in this way, the web service's name is not allowed to be the same as the original name of the package's web service; the new web service needs a new name. Web connections built on the newly named web service definition will not be recognized by the related package canvas object in FME Form 2022.x or older. 

Users who are required to maintain FME package web connections for use in FME Form 2022.x or older must continue to build these connections from the package web service definition installed to their FME Form 2022, and not from a web service created using the Create From functionality in FME Form 2023+.

The FME package canvas object performs differently in different versions of FME Form

FME packages are maintained separately from the core FME Platform applications. This means that FME packages might have new releases between the official releases of FME Form or FME Flow. If users notice that an FME package canvas object produces different results in different versions of FME Form, users should first verify that the version of the FME package in use is consistent between the FME Form versions tested.

In each version of FME Workbench where the package canvas object performed differently, access Tools --> FME Options --> FME packages. In the FME packages list, highlight the FME package under investigation, and look at the package information that populates in the right-side text area. The package version will be listed therein.

If the package version in use differs between the FME Form versions tested, this version difference is one likely source of the behavior difference noticed. Users should upgrade or downgrade the package for all tested FME Form builds so that each FME build uses the same package version. Then, re-test the package canvas object in each FME Form build and see if the behavior difference(s) persist between FME builds. 

The .fmx file of the FME package canvas object can't be edited anymore

Many of the FME package canvas objects (readers/writers and transformers) began as custom transformers, whose .fmx definition files could be edited by users. Users who edited these .fmx files could introduce customized behavior into these canvas objects, to accommodate a variety of unique use cases. However, incorrect behavior was also often introduced when edits to the .fmx file were made.

The .fmx files of FME packages were made non-editable to eliminate unexpected/incorrect behavior in package canvas objects and reduce the troubleshooting effort required to correct these errors.   

Additional Resources 

FME Flow Troubleshooting: Packages

Are you still experiencing issues? 

Please consider posting to the FME Community Q&A if you are still experiencing issues that are not addressed in this article. There are also different support channels available.
 

Have ideas on how to improve this? 

You can add ideas or product suggestions to our Ideas Exchange.