How to Run Java Garbage Collection in Claris FileMaker & Avoid an Unexpected Failure in Windows

What is Java Garbage Collection in Claris FileMaker?

In Claris FileMaker Server 20.1.1, Claris released a new feature to run the Java Garbage Collection to reclaim unused server memory.

It’s crucial to run Garbage Collection frequently in the Web Publishing Engine (WPE). Doing so ensures the server has enough memory to allocate to crucial functions.

It keeps your solutions’ WebDirect memory from ballooning up and becoming unmanageable.

We recommend running Garbage Collection once per day if your Web Direct application causes your server memory to expand much higher than right after FMS is online. Note that this feature requires that you install the Java Development Kit (JDK) and not the Java Runtime Environment (JRE).

How to Run Java Garbage Collection

To run this new feature, navigate to the Admin Console > Connectors > Web Publishing tab under Web Publishing Engine. There, you can find the Java Garbage Collection and free memory used for web publishing on the Primary Machine. You can also schedule a script to run from both Primary and Secondary machines.

Here is how you can run the Java Garbage Collection manually:

Navigate to the Connectors tab in the admin console and then select Run Garbage Collection Now.

The second option allows you to automate the process of cleaning out your web publishing memory. You can set a schedule and forget about the task for the most part. Navigate to the configuration tab > Script and Verify Schedules > Create Schedule > Schedule Type = System script > System script = Sys_Default_RunGarbageCollection (or Sys_Default_RunGarbageCollection_On_Secondary to run the command on a WebDirect Worker machine).

Unfortunately, this scheduled option can fail on Windows if you are using the JAVA_HOME feature that allows you to install the Java JDK system-wide instead of uploading it through the Claris FileMaker Server admin console.  Using JAVA_HOME is our preferred method for installing Java because it persists between FileMaker Server installs and upgrades.

What is the Java Garbage Collection Failure in Windows?

At the end of this blog post, you will find a simple solution to avoid the failure, but we also wanted to take you through our troubleshooting efforts to try and figure out what was happening.  We believe the journey is more interesting than the final result.

If you run Garbage Collection from the connectors tab “Run Garbage Collection Now,” the garbage collection runs properly. However, if you run Garbage Collection as a server schedule “Sys_Default_RunGarbageCollection or Sys_Default_RunGarbageCollection_On_Secondary“, you will always see a “failed” result.

What Causes the Failure?

The Garbage collection triggered through the admin console’s Connector’s tab is executed through the FileMaker Server Admin Console (notably the facstart.sh packaged Node.js). The Garbage Collection through the script schedules (system script “Sys_Default_RunGarbageCollection“) is run through the fmserver process. It is not the same code that runs these two Garbage Collection methods.

First, let’s check how you can perform the Java Garbage Collection yourself without going through Claris FileMaker Server. Make sure that JDK 17 is installed. Then, find the process ID of the running Java process. You can check the process ID using the task manager, as shown in the screenshot below:

With that process id, run the following command in the command line (cmd):

jcmd [PID] GC.run

In our example: jcmd 5312 GC.run

JCMD

jcmd is a utility that is part of the JDK (Java Development Kit) and is used for sending diagnostic command requests to a running Java Virtual Machine (JVM). It provides various runtime information about the JVM and can be used for troubleshooting and monitoring Java applications. Learn more.

You may get a result like this:

“jcmd” is not recognized as an internal or external command, operable program, or batch file.

If so, make sure JDK 17 is installed. Uninstall it, then reinstall it if needed while the FileMaker Server service is offline.

How Java Garbage Collection is Done in the Admin Console Server Process (facstart.sh)

Get the process ID (PID) of the Java process. Run the command:

wmic process where name="java.exe" get processid | MORE +1

On our test machine, that resulted in 5312.

Run the Java Garbage Collection on that running Java process:

jcmd [PID] GC.run

On our machine, that was: jcmd 5312 GC.run

This executes jcmd through the OS environment variables. To find the path of the jcmd executable, execute the following command in the command line:

where jcmd

Your output should show the path to the jcmd utility. In our test machine, the output was: C:\Program Files\Eclipse Adoptium\jdk-17.0.6.10-hotspot\bin\jcmd.exe

Success!

How Java Garbage Collection is Done in the FileMaker Server Process (fmserver.ext)

Getting the process ID (PID) is not done through a command call to wmic using cmd.exe like with the admin console.

Instead, internally, the FileMaker Server runs this command:

"C:\Program Files\FileMaker\FileMaker Server\Web Publishing\java\bin\jcmd.exe" [PID] GC.run

Which results in:

C:\Program Files\FileMaker\FileMaker Server\Web Publishing\java\bin\jcmd.exe is not a valid path.

That is because there is no Java folder in the Web Publishing folder, and consequently, the command fails and shows you the following:

Admin console (notice the “failed” result):

In the Event.log, you will see:

Schedule “sys_run_java_gc” aborted; “Sys_Default_RunGarbageCollection” could not be found or is invalid.

As a side note, if you check the list of schedules in the fmsadmin command line tool, you’ll see that the schedule’s status is “Invalid OS script” after its first run.

Why is there no Java in the FileMaker Server folder structure like the schedule clearly expects?  Because we installed JDK through the JAVA_HOME method. This does not upload Java into the FileMaker Server folder structure but tells FileMaker to use the version of Java installed in the Operating System.

Three Solutions to Overcome This Failure

The first two solutions are the result of working through the problem and are interesting to think about. The third, however, is by far the easiest and, thus, the recommended solution.

1. Run your own script Through a Scheduler

You can create a script that performs the same operations as the FileMaker Server schedule and run your own script through a scheduler. To do so, create a new PowerShell script named “java_gc_run.ps1” in C:\Program Files\FileMaker\FileMaker Server\Data\Scripts

Set it using the Windows Task Scheduler or as a system script schedule in FMS. I’ll proceed with the latter method.

Create two files in the scripts folder:

1. java_gc_run.bat with the following code
   • We’re using a Batch file here to launch the PowerShell because the system script option in FileMaker SErver executes scripts using cmd.exe, which doesn’t work for Powershell scripts. Example (doesn’t work): cmd.exe /c “C:\Program Files\FileMaker\FileMaker Server\Data\Scripts\java_gc.ps1”
   • We’ve chosen Powershell over Batch due to its better error-trapping capabilities.

2. java_gc.ps1 with the following code
   • This file will get the java process ID and then execute the jcmd on it
   • Create a new schedule in the admin console and point it at the “java_gc_run.bat” system script.

@echo off
:: This script invokes a PowerShell script, captures its exit code, and returns to this script so it exits with the same code
cd /d %~dp0
powershell.exe -ExecutionPolicy Bypass -Command "& {&'.\java_gc.ps1'; Exit $LastExitCode}"
SET EXITCODE=%ERRORLEVEL%
exit /b %EXITCODE%

<#
.SYNOPSIS
This script invokes garbage collection for a process in Java. https://www.soliantconsulting.com/blog/java-garbage-collection-filemaker-windows-failure

.DESCRIPTION
The script identifies the process ID of a Java process and uses the tool 'jcmd' 
to tell Java Virtual Machine (JVM) to run garbage collection. 

.PARAMETER None
#>

try
{
    $javaProcessId = Get-Process -Name "java" | Select-Object -ExpandProperty Id
    if ($null -ne $javaProcessId) 
    { 
        $jcmdCommand = "jcmd ${javaProcessId} GC.run"
        Start-Process -NoNewWindow -FilePath "jcmd" -ArgumentList "${javaProcessId} GC.run"
		exit 0
    }
    else
    {
        Write-Warning "No java process found"
	 exit 1
    }
}
catch
{
    Write-Error "An error occurred: $_"
    exit 1
}

2. Trick FileMaker Server with a Redirect

You can also create a symbolic link that “tricks” FileMaker Server into thinking the path is valid, but it actually “redirects” to the correct path of jcmd.

Follow this process:

1. Open the command line tool.
2. Run “where jcmd”
3. Use the JDK installation path provided by the previous command. Example: “C:\Program Files\Eclipse Adoptium\jdk-17.0.6.10-hotspot\bin\jcmd.exe”
4. Run “mklink jcmd.exe “C:\Program Files\Eclipse Adoptium\jdk-17.0.6.10-hotspot\bin\jcmd.exe”
5. Restart the FMS service and try to run the system script from the admin console’s server schedules list.

Either way, both solutions should result in the script schedule running with a “succeeded” result.

3. Re-install the Java JDK

When you install the JDK at the operating system level, the last option to use the JavaSoft registry keys is left unchecked:

It is precisely those registry keys that FileMaker Server is using to detect in its system schedule whether to use the operating system version of the JDK or to go look in its own folder structure.

With that knowledge, the fix is simple: stop your Claris FileMaker Server (at the Windows Services Control Panel level after closing all your files first). Then, repair the JDK installation by selecting the registry option. For good measure, you can reboot your server.

Now, the Garbage Collection schedule will work correctly.

Which Solution to Choose?

We recommend using this third solution as it can persist after FileMaker Server upgrades and does not require writing your own PowerShell or Batch scripts.