Search

How to Setup an Oracle Instant Client for Use with FME

ise
ise
  • Updated

Introduction

You can connect FME Form and FME Flow to Oracle databases using the Oracle Instant Client. This article explains how to install and configure the Oracle Instant Client on Windows, Linux, and macOS, and how to set up environment variables such as TNS_ADMIN and LD_LIBRARY_PATH.
The instructions also cover troubleshooting tips for common connection errors.

Requirements

  • FME Form or FME Flow installed (matching architecture)

  • Oracle Instant Client (matching 32-bit or 64-bit version)

  • Access to an Oracle database

  • Administrative rights to edit environment variables

Important:
The Oracle Client architecture must match your FME installation:

  • 64-bit FME → 64-bit Oracle Client

  • 32-bit FME → 32-bit Oracle Client

Using mismatched architectures may produce errors such as:

"Cannot connect to database because the database client software failed to load."

Step-by-Step Instructions

1. Install the Oracle Instant Client

Windows

  1. Download and unzip the Oracle Instant Client into a directory, for example:
    C:\oracle\instantclient_19_6

  2. Add this directory to the PATH environment variable:

    • Open My Computer > Properties > Advanced > Environment Variables

    • Edit PATH and add the Instant Client directory at the beginning.

    • Do not include quotation marks around the path.

  3. Restart FME to apply the new environment settings.

Linux

FME Form

  1. Download and unzip the Oracle Instant Client into a directory, e.g. /home/fmeuser/instantclient_23_4.

  2. (If required) Create a symlink for the client library:

     
    ln -s libclntsh.so.23.1 libclntsh.so

  3. Set the LD_LIBRARY_PATH environment variable to point to the Instant Client folder:

     
    export LD_LIBRARY_PATH=/home/fmeuser/instantclient_23_4

  4. To set this permanently:

    • Per user: Add the export line to ~/.profile and log out/in.

    • System-wide: Add it to /etc/environment and reboot.

If you receive the error “Oracle client libraries could not be loaded”, install the libaio1 package.

FME Flow

The following instructions assume you have set up systemd on your Linux system to automatically start FME Flow.  (To configure systemd to start FME Flow, see this documentation).

  1. Apply the symlink as described in the FME Form section.

  2. Store the Instant Client in a secure directory such as /opt/oracle/instantclient_23_4.

  3. Edit the systemd service to export the LD_LIBRARY_PATH:

    • Open /etc/systemd/system/fmeflow-engines.service

    • Add this line:

       
      Environment="LD_LIBRARY_PATH=/opt/oracle/instantclient_23_4"

    • Run:

       
      systemctl daemon-reload systemctl restart fmeflow-engines

  4. Review fmeprocessmonitorengine.log to confirm that the path is detected correctly.

  5. Test with a workspace connecting to your Oracle Database.

If not using systemd, add LD_LIBRARY_PATH to /etc/environment.

Note: FME versions 2021–2023.2 do not require a /lib folder for the Instant Client.

macOS

Oracle libraries are not available for Apple Silicon (M1/M2) at this time. Use an Intel macOS system instead.

For:

To learn how to create environment variables on macOS, refer to this article.

2. Connect to Oracle

Option 1: Easy Connect String

Use this format for your dataset connection:

user/password@//hostname:port/service_name

Example:
scott/tiger@//amidala:1521/orcl

With Easy Connect, the username and password are embedded, and no tnsnames.ora file or TNS_ADMIN variable is needed.

If you see an error about NLS data files, define the NLS_LANG environment variable:

NLS_LANG=AMERICAN_AMERICA.WE8ISO8859P1

or for Japanese:

NLS_LANG=JAPANESE_JAPAN.JA16EUC
 

Option 2: Using a TNSNAMES.ORA File

If you prefer to use TNS aliases:

  1. Create a tnsnames.ora file containing service definitions, for example:

    AMIDALA = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = AMIDALA)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = ORCL)) )

  2. Place the file in the same directory as your Instant Client or another location of your choice.

  3. Set the environment variable TNS_ADMIN to point to the folder (not including the filename):

     
    TNS_ADMIN=C:\oracle\instantclient_19_6

Tips:

  • Avoid paths with spaces.

  • Create the file manually to avoid formatting issues.

  • You can share a single tnsnames.ora between 32-bit and 64-bit clients by setting TNS_ADMIN for both.

Troubleshooting

  • If Oracle formats are greyed out in the Formats Gallery, see Oracle Database Reader/Writer Setup for help.

  • If you cannot connect using a TNS alias, test with the Easy Connect string directly (e.g., hostname:port/service_name).

You can also verify database access using tools such as SQLDeveloper or Toad. Successful connections in those tools indicate that FME should connect correctly as well.

Additional Resources

Was this article helpful?

We're sorry to hear that.

Please tell us why.

As of January 14th, 2026, comments on knowledge base articles have been closed. To make sure questions don’t get missed and to enable more community support, we’ve moved discussions to the FME Community. If you have a question or a comment about this article, please create a new post or create a support ticket.