Why Does the Ignition Vision Client Fail on Raspberry Pi 5?

Fixes That Fail on an AARCH64 Panel

The setup is an Ignition Edge 8.1.45 gateway on a Raspberry Pi 5 (16 GB) running Ubuntu Desktop 24.10. The gateway installs cleanly from the ARM (aarch64) package. Remote Designer and remote Vision Clients work. The failure appears only when the Pi tries to run its own local Vision Client, which is the Edge Panel use case. Engineers usually try the following fixes, in roughly this order:

Each of these attacks the Java layer. The blocker sits one layer lower, in native code.

Instruction-Set Mismatch in Native Libraries

What decides the outcome is the CPU architecture (ISA) each binary was compiled for. Java bytecode is portable. The JVM that executes it is not, and neither are the JNI shared objects (.so) a Java application loads at runtime. Before mapping a library, the dynamic loader checks the ELF header's machine field. An library cannot load into an aarch64 process, so the JVM throws an UnsatisfiedLinkError with the AMD64-on-AARCH64 wording shown above. This is architecture, not configuration. No JVM flag or classpath change fixes it.

The native pieces are the bundled JRE and the UI and browser stacks the launchers depend on: JavaFX and the Chromium-based embedded browser (JxBrowser). None of these ship for Linux/ARM in the launcher packages. The same limit applies to Vision's Web Browser component. A Vision window that contains it fails on the Pi even when the client itself launches.

Run these three checks to confirm the mismatch directly on the Pi:

1. uname -m should return aarch64.
2. java -XshowSettings:properties -version 2>&1 | grep os.arch should report aarch64. If it reports amd64, you are under emulation or pointing at the wrong JDK.
3. Extract the offending library from the launcher jar or its cache directory and run file <library>.so. The output reads ELF 64-bit LSB shared object, x86-64.

Component Support Matrix on Linux/ARM

So Edge Panel on the Pi is partially supported. The gateway is supported. The supported local HMI path is Perspective in the Pi's browser. A local Vision Client is possible only through the legacy script.

JPMS Module-Access Failure After Switching Scripts

Once you move to legacyClient.sh and an ARM-native JDK, the architecture error goes away. The next failure is a Java module-system check that stops the client during startup:

WARNING: JPMS Module java.desktop Does not open the correct packages to ALL-UNNAMED.
com.inductiveautomation.ignition.client.launch.steps.ValidationException:
  JPMS Module opens/export check failed! check your --add-opens and --add-exports clauses
  at ...CheckJpmsRequirementsStep.run(CheckJpmsRequirementsStep.java:33)

Since Java 17, the JDK enforces strong encapsulation of internal packages by default. The Vision client uses reflection into internal packages of modules such as java.desktop. That access has to be granted explicitly on the command line with --add-opens <module>/<package>=ALL-UNNAMED and --add-exports <module>/<package>=ALL-UNNAMED. CheckJpmsRequirementsStep verifies those grants before the client proceeds. If any required package is missing, the launch aborts.

Two things cause this error:

• Incomplete flag list. Adding a few --add-opens clauses is not enough. The check wants the full set the client expects.
• Wrong JDK major version. The gateway runs Java 17. Installing JDK 21 on the Pi puts a different runtime under the client than the one the 8.1 flag set and the published Linux Java 17 opens/exports guidance target. Use JDK 17.

Do not guess the package list. Read it from a working launch, as described in the next section.

Procedure: Launching a Vision Client on the Pi with legacyClient.sh

Build and debug the whole stack on x86 Linux first, then port only the scripts to the Pi. That way you separate architecture problems from command-line problems.

1. Build an x86 reference machine. Install Linux with the XFCE desktop on an x86 PC. Install the standard Vision Client Launcher and launch a client against the Pi's Edge gateway.
2. Capture the known-good command line. Open the launcher's log file and copy the final java command it executes. You need the full --add-opens/--add-exports list, memory arguments, main class, and the gateway and project arguments.
3. Get the legacy script. Download legacyClient.sh using the instructions in the Inductive Automation support article on Ignition 8 32-bit Vision Clients.
4. Merge the flags. Edit the java invocation in legacyClient.sh so its JVM options match the captured command line. Apply the published Linux Java 17 opens/exports modifications as well.
5. Prove it on x86. Run the edited script on the x86 machine with a system JDK 17. Keep editing until the client reaches the login or project screen with no ValidationException.
6. Prepare the Pi runtime. On the Pi, install an ARM-native JDK 17, for example sudo apt install openjdk-17-jdk. Select it with sudo update-alternatives --config java, then confirm java -version reports 17 and os.arch reports aarch64.
7. Fix script hygiene. Copy the script to the Pi and run chmod +x legacyClient.sh. If the file was edited on Windows, strip carriage returns with sed -i 's/\r$//' legacyClient.sh. CRLF line endings break the shebang and produce misleading errors. Check the shebang points at a shell that exists on Ubuntu.
8. Launch and read the log. Run the script from a terminal on the Pi desktop. If the only remaining errors are native-library loads, find the screen element that triggers them, usually a Web Browser component, and remove it.

Kiosk Session: Auto-Login, .Xsession, Fullscreen Relaunch

A panel needs to boot straight into the client and recover if the client exits. The standard Linux pattern gives you a watchdog for free:

1. Use XFCE as the desktop environment. It is lighter on the Pi than the default Ubuntu desktop.
2. Create a dedicated panel user. Enable the login manager's auto-login for that user.
3. Give that user a custom .Xsession that launches the Vision Client instead of the normal desktop.
4. Configure legacyClient.sh to open the client in fullscreen launch mode. Take the exact launch-mode argument from the x86 launcher log you captured.

#!/bin/sh
# ~/.Xsession for the panel user
exec /home/panel/legacyClient.sh

Using exec ties the X session's lifetime to the client process. When the client exits for any reason (crash, gateway restart, operator close), the session ends and the login manager comes back. Auto-login then relaunches the client unless someone interrupts it manually at the login screen. Technicians still get a maintenance path, and you avoid a separate supervisor daemon.

Verification and Deployment Limits

Before you call a Pi panel good, confirm each of these:

• ps -eo pid,args | grep java shows the ARM JDK 17 path and the full --add-opens set.
• The client log contains no ValidationException and no UnsatisfiedLinkError.
• Killing the Java process returns the panel to the client within one login cycle.
• Every window deployed to the Pi opens without errors. Screens containing a Web Browser component are excluded.
• A gateway restart causes the client to reconnect, or to exit and relaunch.

Choose the HMI path by what the panel has to do:

Low-cost stations built from a Pi, the official 7-inch touchscreen and a custom enclosure (roughly $250 per station) run as Vision clients on simple machines in production. Some sites wire the Pi to machine status and count signals and push data to the gateway through the WebDev module. Fleets of 80+ such stations have been moved to Perspective sessions where the panel has no machine interface. Edge Panel itself, meaning a local gateway plus a local client, is rarely seen on the Pi in production.

For a training lab, decide by what students need to practice. If they must practice the full Edge Panel workflow, including the Vision Client Launcher, Designer and client on the same hardware, use x86 Linux panels. The Pi cannot do that. If a Pi gateway with Perspective in the local browser and Designer on lab PCs is acceptable, the Pi works and stays on the supported path through upgrades.

FAQ