Updating Java Options for Spotfire TERR and Python Services

Keywords:
TERR, Python service, custom.properties, JavaOptions, -Xms, -Xmx, OutOfMemoryError, JVM options

Introduction: This KB explains how to update Java VM options for Spotfire TERR and Python services by editing the service custom.properties file. The focus is on adding or adjusting the JavaOptions setting (for example -Xms and -Xmx) to prevent memory-related failures such as OutOfMemoryError: unable to create native thread and CreateProcess error=8.

Symptoms/Example Errors:

• java.lang.OutOfMemoryError: unable to create native thread: possibly out of memory or process/resource limits reached
• java.io.IOException: Cannot run program "...jdk\bin\java": CreateProcess error=8, Not enough memory resources are available to process this command
• Service shuts down or fails to spawn new engine processes.

Scope: Applies to configuring the Spotfire TERR service and the Spotfire Python service via their exported custom.properties configuration. See the product-specific docs for additional context:

• Managing Java Options — Spotfire Python Service (example)
• Managing Java Options — TERR Service (example)

Solution:

1. Locate the service configuration (custom.properties)

   Identify the custom.properties file for the service you want to modify. The typical path after exporting a configuration is:

   <server installation dir>/tomcat/spotfire-bin/config/root/conf/<deployment area>/<config-name>/custom.properties

   If you do not have a custom.properties file yet, export the service configuration using the Spotfire config export-service-config command for the appropriate capability (TERR or PYTHON), then edit the exported file.

2. Edit the custom.properties file to add JavaOptions

   Open custom.properties in a plain-text editor and add or update the JavaOptions entry. Example:

   JavaOptions: -Xms2g,-Xmx4g

   Notes:

   • No surrounding quotes are required—enter the options exactly as shown.
   • Multiple JVM options are comma-separated, as in the example.
   • Adjust values to match available system memory and expected workload. Example starting ranges:
     • Light workloads:-Xms512m,-Xmx1g
     • Medium workloads:-Xms2g,-Xmx4g
     • Heavy workloads:-Xms4g,-Xmx8g
   • Do not set -Xmx higher than available physical memory minus what other processes require.

3. Save, import configuration, and apply to service

   After saving the edited custom.properties file, import the configuration back into Spotfire and apply it to the service. Example command:

   config import-service-config --capability=<TERR or PYTHON> --deployment-area=<your deployment area name> --file=<path to custom.properties>

   After a successful import, restart the corresponding service so the new JVM options take effect (service restart is required for JVM options).