Scala: GraalVM native-image: Warning: Image 'ffx' is a fallback image that requires a JDK

As a brief note to self, this weekend I was trying to create a GraalVM native executable named ffx from a Scala project, and I got this error during the GraalVM native-image compilation process:

GraalVM native-image: Warning: Image 'ffx' is a fallback image that requires a JDK
for execution (use --no-fallback to suppress fallback image generation and to print 
more detailed information why a fallback image was necessary).

Then I tried to create the native image using the --no-fallback option, but that failed.

So I then went back to creating a GraalVM native image with the fallback image — which works in my local directory — but when I copied the executable to a new directory it stopped working. Then I found this FALLBACK_EXECUTOR_VERBOSE environment variable setting somewhere on the internet, and it helped me see the problem. Basically you set the environment variable before you run your native image, which is ffx in this case:

$ FALLBACK_EXECUTOR_VERBOSE=true ffx
Exec: /Users/al/bin/graalvm-ce-java11-20.1.0/Contents/Home/bin/java 
  -Dorg.graalvm.nativeimage.kind=fallback-executable -cp /Users/al/bin/scala-2.12.15/lib/scala-library.jar:/Users/al/bin/MultiPatternFileFind-assembly-0.2.jar multi_pattern_filefind.MultiPatternFileFind
Error: Could not find or load main class multi_pattern_filefind.MultiPatternFileFind
Caused by: java.lang.ClassNotFoundException: multi_pattern_filefind.MultiPatternFileFind

The problem was that the GraalVM native executable (the fallback image) needed the MultiPatternFileFind-assembly-0.2.jar JAR file, but it couldn’t find it, because I hadn’t copied it to my ~/bin directory. Once I copied the JAR file there, my ffx command began working again as desired.

So, lesson learned, if you ever need to debug a GraalVM native executable that uses a fallback image, the FALLBACK_EXECUTOR_VERBOSE environment variable is your friend.