Configure and Maintain the JVM Temporary Files Directory¶
This page explains how Fusion Metadata Registry (FMR) uses the JVM temporary files directory, how to size it correctly, and how to maintain it safely over time.
For FMR deployments, the temporary directory is not a minor housekeeping detail. It is a critical runtime dependency. Administrators should treat it as planned application storage with explicit capacity, performance, and maintenance controls.
Why the temporary directory matters¶
FMR uses the JVM temporary files directory for workloads that cannot be completed entirely in memory.
In practice, the directory is used for two main purposes:
- scratch space for large data-processing operations
- swap storage for structural metadata objects
This means the temporary directory directly affects:
- whether large processing jobs complete successfully
- how well the system performs under load
- how resilient the deployment is after failures or restarts
FMR 12 places more importance on this directory than earlier releases because it is used not only for transient processing files, but also as swap space for structural metadata storage.
What FMR stores in the temporary directory¶
You should expect to see several kinds of files in the configured temp location.
Typical examples include:
- data-processing scratch files such as
tmpFile3576981487234860963sdmxsource_tmp - H2 MVStore files used during operations such as sorting and consolidation, for example
sdmxdb10659392859918503335.mvs - structural metadata swap objects, for example
8a2cb158-7050-456d-81ac-123a15a4d6be
These files are part of normal operation. Their presence does not by itself indicate a problem. The administrative concern is whether the directory has enough free space and whether stale files are being removed regularly.
Plan capacity before go-live¶
The most important administrative task is to size the temporary directory for the expected workload.
For large data-processing operations, FMR may require temporary space of between two and three times the size of the uncompressed source dataset. For example, processing a 2 GB SDMX-ML dataset may require up to 6 GB of free temporary space.
This requirement becomes more significant when:
- datasets are large
- multiple users run processing jobs at the same time
- scheduled jobs overlap with interactive use
- the deployment performs structure mapping or similar heavy transformations
In busy environments, it is reasonable to provision 100 GB or more of temporary space.
The structural metadata swap requirement is usually much smaller, but it should still be planned for. Provisioning around 1 GB for structural metadata swap is sufficient in most environments. However, this can grow when semantic versioning is used heavily, because each revision may result in an additional stored copy of the structure.
When sizing the directory, administrators should explicitly answer these questions:
- What is the largest uncompressed dataset the deployment is expected to process?
- How many large jobs may run concurrently?
- Will batch processing and user-driven workloads overlap?
- How much additional headroom is needed for stale files between maintenance cycles?
If these questions are not answered in advance, temporary storage problems usually appear first as intermittent production issues rather than as a clean startup failure.
Choose an appropriate storage location¶
The temporary directory should be placed on storage that is both large enough and fast enough for the workload.
FMR can perform substantial read and write activity in this location during large processing operations. Slow disks may not cause immediate failures, but they can increase job duration and reduce responsiveness under load. This is especially noticeable when multiple large operations run concurrently.
As a general rule, choose a location that:
- has predictable free capacity
- is isolated from unrelated system temp usage where possible
- uses storage with good I/O performance
- is included in operating-system-level monitoring and alerting
Avoid relying on a small default OS temp area if the server also hosts other applications or background jobs.
What happens when temp space is insufficient¶
When the temporary directory is undersized, full, unavailable, or poorly maintained, the symptoms usually include:
- poor performance on large data-processing operations
- intermittent service instability
- application failures or crashes
In the FMR logs, these problems are typically reported as I/O exceptions.
Example log messages:
2026-08-09 16:49:46.426 ERROR http-nio-8080-exec-10 io.sdmx.core.data.manager.DataValidationReportManagerImpl - Validation error:
io.sdmx.api.exception.SdmxException: IO Exception whilst trying to write to file output stream: file:/fmr/tmp/tmpFile16520994157286769296sdmxsource_tmp
at io.sdmx.utils.core.io.OverflowWriteableDataLocation$Buffer.write(OverflowWriteableDataLocation.java:152)
2026-08-09 16:49:46.426 ERROR http-nio-8080-exec-10 io.sdmx.core.data.manager.DataValidationReportManagerImpl - Validation error:
io.sdmx.api.exception.SdmxException: IO Exception whilst trying to write to file output stream: file:/fmr/tmp/tmpFile16520994157286769296sdmxsource_tmp
at io.sdmx.utils.core.io.OverflowWriteableDataLocation$Buffer.write(OverflowWriteableDataLocation.java:152)
at com.ctc.wstx.io.UTF8Writer.write(UTF8Writer.java:143)
2026-08-09 16:54:17.466 ERROR http-nio-8080-exec-9 io.sdmx.core.data.model.validate.DatasetDetailsImpl - Error reading dataset
org.h2.mvstore.MVStoreException: Writing to sun.nio.ch.FileChannelImpl@139bc40 failed; length 544768 at 95522816 [2.4.240/2]
at org.h2.mvstore.DataUtils.newMVStoreException(DataUtils.java:996)
If you see errors like these, check the temp directory immediately for:
- available disk space
- filesystem permissions
- mount availability
- accumulation of old
*_tmpand*.mvsfiles
Maintenance is required¶
FMR does not assume that every temporary file can always be removed cleanly by the application itself. Application crashes, forced restarts, server interruptions, and other incidents can leave stale temporary files behind.
For that reason, production deployments should implement automated operating-system-level maintenance for the temp directory.
The recommended approach is:
- Purge the FMR temp directory before the FMR web application starts.
- Periodically delete stale temporary processing files that are no longer in use.
At minimum, periodic cleanup should target files matching:
*_tmp*.mvs
A sensible default policy is to delete those files when they are more than one hour old. This is conservative enough for most deployments while still preventing long-term accumulation.
Administrators should only automate deletion in a temp directory that is dedicated to FMR or where the cleanup pattern is tightly scoped to FMR-created files.
The example below assumes FMR uses /usr/local/tomcat/temp as its dedicated temporary directory.
Clean the directory before startup¶
Create a startup preparation script such as:
Run this script before Tomcat or the application server starts FMR.
Periodic cleanup with cron¶
Add a cron entry such as:
15 * * * * find /usr/local/tomcat/temp -maxdepth 1 -type f \( -name '*_tmp' -o -name '*.mvs' \) -mmin +60 -delete
This removes stale scratch and MVStore files older than 60 minutes at 15 minutes past each hour.
If your deployment does not use a dedicated temp directory, narrow the cleanup rule carefully so it only affects FMR-generated files.
The example below assumes FMR uses D:\FMR\tmp as its dedicated temporary directory.
Clean the directory before startup¶
Create a PowerShell script such as:
Run this script before the Windows service or application server starts FMR.
Periodic cleanup with Task Scheduler¶
Use Windows Task Scheduler to run a PowerShell command on a repeating schedule:
Get-ChildItem -Path 'D:\FMR\tmp' -File |
Where-Object {
$_.LastWriteTime -lt (Get-Date).AddHours(-1) -and
($_.Name -like '*_tmp' -or $_.Extension -eq '.mvs')
} |
Remove-Item -Force
This removes stale FMR processing files older than one hour.
As on Linux, only use broad deletion rules when the directory is dedicated to FMR.
Where the JVM temp directory is configured¶
The JVM temporary directory is controlled by the java.io.tmpdir system property.
You can set it explicitly with:
In containerized and scripted deployments, setting java.io.tmpdir directly is often the clearest and most portable option.
Apache Tomcat deployments¶
In Apache Tomcat, the default temp directory is $CATALINA_BASE/temp.
Tomcat also allows the temporary directory to be controlled with the CATALINA_TMPDIR environment variable. In many Tomcat-based FMR deployments, this is the simplest way to move temporary files to a dedicated filesystem with more capacity.
Examples:
- Linux:
export CATALINA_TMPDIR=/opt/fmr/tmp - Windows: set
CATALINA_TMPDIR=D:\FMR\tmp
If you prefer, you can instead set -Djava.io.tmpdir in the Tomcat JVM options. Use one clear approach consistently and document it in your deployment procedure.
Container and Kubernetes deployments¶
In containers, do not rely on the image's default temp location without checking the available writable space first.
For Kubernetes and similar platforms:
- mount a volume specifically for temporary files
- set
-Djava.io.tmpdirto that mounted path - ensure the volume size reflects peak concurrent workload, not just average usage
- implement monitoring so the pod does not silently run out of temp space
Ephemeral container storage may be acceptable for small workloads, but larger or bursty processing jobs usually need explicitly sized storage.
Recommended administrator checklist¶
Before putting an FMR deployment into production, confirm that:
- the temp directory location is explicitly chosen and documented
- the filesystem has enough capacity for peak workload and concurrency
- the storage performance is appropriate for large temporary I/O
- automated startup cleanup is in place
- periodic stale-file cleanup is in place
- disk space monitoring and alerting cover the temp filesystem
- support staff know that temp-directory issues commonly appear as I/O exceptions in the FMR logs