CRaC Command-Line Options and System Properties

Table of Contents

Command-Line Options
System Properties

Need help?

Schedule a consultation with an Azul performance expert.

Command-Line Options

Java command-line options that control the behavior of CRaC.

Note	The following options are applicable to Azul Zulu. For options applicable to Azul Zing, refer to the column "Zing".

Command Line Option Description Default Zing

Command Line Option	Description	Default	Zing
-XX:CRaCCheckpointTo=<value>	Directory path where the checkpoint must be created. The value is required. To store the checkpoint in an S3-compatible bucket (only available with the Warp CRaC engine), set the `<value>` to, for example, `s3://bucket/some-key`. See Using CRaC on Amazon Web Services (AWS) > S3 Storage
-XX:CRaCRestoreFrom=<value>	The directory path where the CRaC image is stored which must be used for the restore. It replaces the initializing virtual machine on successful restore. The value is required. You can optionally pass the name of a new main class and its arguments when using this option. In such a case, the new main method will be invoked with the specified arguments by the thread that initiated the checkpoint, after all CRaC resources have been successfully processed. Check Restoring With New Arguments for more info.
-XX:CRaCEngine=<value>	Integrated engines in Zulu: `criu`: Engine using Linux CRIU (Checkpoint/Restore In Userspace). `warp`: Engine which doesn’t require any additional capabilities, neither for checkpoint nor for restore. `simengine` and `pauseengine`: Simulation engines used for development purposes only. For more information, see CRaC Engines.	On Linux: `criu` On macOS and Windows: `simengine`	`warp` only
-XX:CRaCEngineOptions=<value>	A comma-delimited list of `key=value` to specify the behavior of the selected CRaC engine. Use the value `help`, in the exact format `-XX:CRaCEngineOptions=help`, to get the full list of available options for the selected `CRaCEngine`. This will let the JVM print the list of supported options and exit. More info about the available options is documented below for the CRIU and Warp engines.	null
-XX:CRaCMinPid=<value>	The minimal PID value for a process that is restored. See Debugging Coordinated Restore at Checkpoint Failures > Using the CRaCMinPid Option. The default value is 128 only if the Java process is started with PID 1 (e.g., in a container). For processes started with a different PID, the PID is not adjusted unless this option is set.	128
-XX:+/-CRaCResetStartTime	Reset JVM’s start time and uptime on restore.	true
-XX:+/-CRaCIgnoreRestoreIfUnavailable	If the checkpoint image specified for the restore (with `-XX:CRaCRestoreFrom`) is identified as being unusable, the JVM will continue with the normal startup instead of failing. Enabling this option does not guarantee that the normal startup will follow any failed restore attempt, it only covers an early image/environment verification. Available in Azul Zulu 25 and October 2025 releases: When restoring with this option, you should specify a main class and its arguments as usual. If the CRaC restore succeeds, these arguments are ignored, but if the restore fails, they are used for the normal startup process. See Transparent Restore or Startup for more info.	false
-XX:CRaCIgnoredFileDescriptors=<value>	Comma-separated list of file descriptor numbers or paths. All the file descriptors greater than 2 (stdin, stdout and stderr are excluded automatically), that are not in this list, are closed when the VM starts.	null
-XX:+/-CRaCAllowToSkipCheckpoint	Allow the implementation to not call the Checkpoint if the helper can not be found.	false
-XX:CRaCAllowedOpenFilePrefixes=<value>	List of path prefixes for files that can be open during the checkpoint. CRaC won’t throw an error upon detecting these and leaves the handling up to the Checkpoint/Restore engine. This option applies only to files opened by native code. For files opened by Java code use `-Djdk.crac.resource-policies=…`.	`/var/lib/sss/mc/` (on Linux)
-XX:+/-CRaCHeapDumpOnCheckpointException	Dump the heap when a `CheckpointException` is thrown because of a failing CRaC precondition.	false
-XX:+/-CRaCPrintResourcesOnCheckpoint	Print the resources used to decide on a CheckpointException. This is a diagnostic feature and must be preceded with `-XX:+UnlockDiagnosticVMOptions`.	false
-XX:+/-CRaCTraceStartupTime	Trace the startup time.	false
-XX:+/-CRaCDoThrowCheckpointException	Throw `CheckpointException` if resource handle is found that can’t be checkpointed.	true
-XX:+/-CRaCPauseOnCheckpointError	Pauses the checkpoint when a problem is found on the JVM level.	false
-XX:CRaCMaxHeapSizeBeforeCheckpoint=<value>	The maximum size of the heap before the checkpoint. By default, this equals to `-Xmx`.	0
-XX:CPUFeatures=<value>	The CPU feature set. Use `-XX:CPUFeatures=0xnumber` with `-XX:CRaCCheckpointTo` when you get an error during `-XX:CRaCRestoreFrom` on a different machine (with another architecture). This option is only available on x86. `native` is the default (and fastest) `ignore` disables the CPU features check `generic` is compatible but slower compared to `native`	native
-XX:+/-ShowCPUFeatures	Show the features of this CPU to be possibly used for the `-XX:CPUFeatures=0xnumber` option. This option is only available on x86.	false
-XX:+/-IgnoreCPUFeatures	EXPERIMENTAL! Flag defining to continue to run after `-XX:CRaCRestoreFrom` finds out some CPU features are missing. This option is only available on x86.	false

-XX:CRaCCheckpointTo=<value>

Directory path where the checkpoint must be created. The value is required.

To store the checkpoint in an S3-compatible bucket (only available with the Warp CRaC engine), set the <value> to, for example, s3://bucket/some-key. See Using CRaC on Amazon Web Services (AWS) > S3 Storage

-XX:CRaCRestoreFrom=<value>

The directory path where the CRaC image is stored which must be used for the restore. It replaces the initializing virtual machine on successful restore. The value is required.

You can optionally pass the name of a new main class and its arguments when using this option. In such a case, the new main method will be invoked with the specified arguments by the thread that initiated the checkpoint, after all CRaC resources have been successfully processed. Check Restoring With New Arguments for more info.

-XX:CRaCEngine=<value>

Integrated engines in Zulu:

criu: Engine using Linux CRIU (Checkpoint/Restore In Userspace).
warp: Engine which doesn’t require any additional capabilities, neither for checkpoint nor for restore.
simengine and pauseengine: Simulation engines used for development purposes only.

For more information, see CRaC Engines.

On Linux:
criu

On macOS and Windows:
simengine

warp only

-XX:CRaCEngineOptions=<value>

A comma-delimited list of key=value to specify the behavior of the selected CRaC engine.

Use the value help, in the exact format -XX:CRaCEngineOptions=help, to get the full list of available options for the selected CRaCEngine. This will let the JVM print the list of supported options and exit.

More info about the available options is documented below for the CRIU and Warp engines.

null

-XX:CRaCMinPid=<value>

The minimal PID value for a process that is restored. See Debugging Coordinated Restore at Checkpoint Failures > Using the CRaCMinPid Option.

The default value is 128 only if the Java process is started with PID 1 (e.g., in a container). For processes started with a different PID, the PID is not adjusted unless this option is set.

128

-XX:+/-CRaCResetStartTime

Reset JVM’s start time and uptime on restore.

true

-XX:+/-CRaCIgnoreRestoreIfUnavailable

If the checkpoint image specified for the restore (with -XX:CRaCRestoreFrom) is identified as being unusable, the JVM will continue with the normal startup instead of failing. Enabling this option does not guarantee that the normal startup will follow any failed restore attempt, it only covers an early image/environment verification.

Available in Azul Zulu 25 and October 2025 releases: When restoring with this option, you should specify a main class and its arguments as usual. If the CRaC restore succeeds, these arguments are ignored, but if the restore fails, they are used for the normal startup process. See Transparent Restore or Startup for more info.

false

-XX:CRaCIgnoredFileDescriptors=<value>

Comma-separated list of file descriptor numbers or paths. All the file descriptors greater than 2 (stdin, stdout and stderr are excluded automatically), that are not in this list, are closed when the VM starts.

null

-XX:+/-CRaCAllowToSkipCheckpoint

Allow the implementation to not call the Checkpoint if the helper can not be found.

false

-XX:CRaCAllowedOpenFilePrefixes=<value>

List of path prefixes for files that can be open during the checkpoint. CRaC won’t throw an error upon detecting these and leaves the handling up to the Checkpoint/Restore engine. This option applies only to files opened by native code. For files opened by Java code use -Djdk.crac.resource-policies=….

/var/lib/sss/mc/ (on Linux)

-XX:+/-CRaCHeapDumpOnCheckpointException

Dump the heap when a CheckpointException is thrown because of a failing CRaC precondition.

false

-XX:+/-CRaCPrintResourcesOnCheckpoint

Print the resources used to decide on a CheckpointException. This is a diagnostic feature and must be preceded with -XX:+UnlockDiagnosticVMOptions.

false

-XX:+/-CRaCTraceStartupTime

Trace the startup time.

false

-XX:+/-CRaCDoThrowCheckpointException

Throw CheckpointException if resource handle is found that can’t be checkpointed.

true

-XX:+/-CRaCPauseOnCheckpointError

Pauses the checkpoint when a problem is found on the JVM level.

false

-XX:CRaCMaxHeapSizeBeforeCheckpoint=<value>

The maximum size of the heap before the checkpoint. By default, this equals to -Xmx.

-XX:CPUFeatures=<value>

The CPU feature set. Use -XX:CPUFeatures=0xnumber with -XX:CRaCCheckpointTo when you get an error during -XX:CRaCRestoreFrom on a different machine (with another architecture).

This option is only available on x86.

native is the default (and fastest)
ignore disables the CPU features check
generic is compatible but slower compared to native

native

-XX:+/-ShowCPUFeatures

Show the features of this CPU to be possibly used for the -XX:CPUFeatures=0xnumber option.

This option is only available on x86.

false

-XX:+/-IgnoreCPUFeatures

EXPERIMENTAL! Flag defining to continue to run after -XX:CRaCRestoreFrom finds out some CPU features are missing.

This option is only available on x86.

false

CRIU Engine Options

These are a few of the most used options that are available for -XX:CRaCEngineOptions=<value> when using the CRIU Based Engine. For the full list, start your JVM with -XX:CRaCEngine=criu -XX:CRaCEngineOptions=help.

Engine Option Description Default

Engine Option	Description	Default
keep_running=<true/false>	Keep the process running after the checkpoint or kill it.	false
direct_map=<true/false>	On restore, map process data directly from saved files. This may speedup the restore but the resulting process will not be the same as before the checkpoint.	true
compression=<true/false>	Enable image compression with default parameters. Can be used for the creation of a checkpoint, on restore compression is detected automatically.	false
args=<string>	Free space-separated arguments, passed directly to the engine executable, e.g. `--arg1 --arg2 --arg3`. This can be used to set: Logging verbosity: `-v <level>` with the level between 0 (off) and 4 (debug). Log file: `-o <filename>`.	empty string

keep_running=<true/false>

Keep the process running after the checkpoint or kill it.

false

direct_map=<true/false>

On restore, map process data directly from saved files. This may speedup the restore but the resulting process will not be the same as before the checkpoint.

true

compression=<true/false>

Enable image compression with default parameters. Can be used for the creation of a checkpoint, on restore compression is detected automatically.

false

args=<string>

Free space-separated arguments, passed directly to the engine executable, e.g. --arg1 --arg2 --arg3.

This can be used to set:

Logging verbosity: -v <level> with the level between 0 (off) and 4 (debug).
Log file: -o <filename>.

empty string

Warp Engine Options

These are a few of the most used options that are available for -XX:CRaCEngineOptions=<value> when using the Warp Engine. For the full list, start your JVM with -XX:CRaCEngine=warp -XX:CRaCEngineOptions=help.

Engine Option	Description	Default	Zing
keep_running=<true/false>	On checkpoint, keep the application running after the checkpoint or kill it.	false
direct_map=<true/false>	On restore, map process data directly from saved files. This may speed up the restore but the resulting process will not be the same as before the checkpoint.	false
compression=<true/false>	Enable image compression with default parameters. Can be used for the creation of a checkpoint, has no effect on restore.	false
concurrent=<true/false>	Continue application threads before the whole memory is restored. If a thread tries to access a yet-not-restored memory it gets blocked until the memory is restored. Should be specified on restore, has no effect on checkpoint.	false	true
optimization.profiling_runs=<unsigned int>	Perform the specified number of profiling runs: in each run a restore is performed and the order in which pages are loaded is recorded. Each profiling run ends when the whole memory has been loaded. The gathered statistics can then be used to speed-up restore.	0	Not supported
s3.endpoint=<url>	Can be set to use a custom S3-compatible storage accessible via the specified HTTP endpoint instead of AWS S3. See Using CRaC on Amazon Web Services (AWS) > Using S3 Storage.	<AWS S3 URL>

Engine Option

Description

Default

Zing

keep_running=<true/false>

On checkpoint, keep the application running after the checkpoint or kill it.

false

direct_map=<true/false>

On restore, map process data directly from saved files. This may speed up the restore but the resulting process will not be the same as before the checkpoint.

false

compression=<true/false>

Enable image compression with default parameters. Can be used for the creation of a checkpoint, has no effect on restore.

false

concurrent=<true/false>

Continue application threads before the whole memory is restored. If a thread tries to access a yet-not-restored memory it gets blocked until the memory is restored. Should be specified on restore, has no effect on checkpoint.

false

true

optimization.profiling_runs=<unsigned int>

Perform the specified number of profiling runs: in each run a restore is performed and the order in which pages are loaded is recorded. Each profiling run ends when the whole memory has been loaded. The gathered statistics can then be used to speed-up restore.

Not supported

s3.endpoint=<url>

Can be set to use a custom S3-compatible storage accessible via the specified HTTP endpoint instead of AWS S3. See Using CRaC on Amazon Web Services (AWS) > Using S3 Storage.

Deprecated Command-Line Options

With the Zulu release of July 2025, multiple CRaC engine options got deprecated and are now incorporated into CRaCEngineOptions. These options can still be used, but will be removed in the release of July 2026.

Command Line Option Description Default

Command Line Option	Description	Default
-XX:+/-CRaCKeepRunning	Flag defining to not terminate the process after the checkpoint.	false
-XX:+/-CRaCConcurrentMemoryLoading	Used for restore to start the restored process before the image is fully unpacked into memory. As applications usually don’t require all data to perform some useful work, this can improve the startup lag. Direct memory mapping (non-compressed) is extremely fast compared to regular loading. Compressed images are slower as they need to be uncompressed. `-XX:+CRaCConcurrentMemoryLoading` may improve the time to the first operation after restore for large images. For small images, the effect may be negative.	false
-XX:+/-CRaCDirectMapImage	Flag to define if the checkpoint image is mapped into memory directly (true), or read into anonymous memory map (false). Direct mapping usually results in faster restore, but operations accessing the memory for the first time might experience decreased performance as the content is paged-in lazily.	true
-XX:CRaCOptimizeImage=<value>	After checkpoint, the image can be automatically reordered, based on the loading order in the profiling runs. This option sets the number of profiling runs. The default value of 0 means no optimization. With Warp, you can use the option `-XX:CRaCOptimizeImage=N` to perform N training runs to create checkpoints. After the checkpoint image is created, Warp iteratively performs N restores and determine the optimal layout of the image.	0
-XX:+/-CRaCImageCompression	Compress the CRaC image during the checkpoint. Upon restore, the compressed format is detected automatically.	false

-XX:+/-CRaCKeepRunning

Flag defining to not terminate the process after the checkpoint.

false

-XX:+/-CRaCConcurrentMemoryLoading

Used for restore to start the restored process before the image is fully unpacked into memory. As applications usually don’t require all data to perform some useful work, this can improve the startup lag.

Direct memory mapping (non-compressed) is extremely fast compared to regular loading. Compressed images are slower as they need to be uncompressed. -XX:+CRaCConcurrentMemoryLoading may improve the time to the first operation after restore for large images. For small images, the effect may be negative.

false

-XX:+/-CRaCDirectMapImage

Flag to define if the checkpoint image is mapped into memory directly (true), or read into anonymous memory map (false). Direct mapping usually results in faster restore, but operations accessing the memory for the first time might experience decreased performance as the content is paged-in lazily.

true

-XX:CRaCOptimizeImage=<value>

After checkpoint, the image can be automatically reordered, based on the loading order in the profiling runs. This option sets the number of profiling runs. The default value of 0 means no optimization.

With Warp, you can use the option -XX:CRaCOptimizeImage=N to perform N training runs to create checkpoints. After the checkpoint image is created, Warp iteratively performs N restores and determine the optimal layout of the image.

-XX:+/-CRaCImageCompression

Compress the CRaC image during the checkpoint. Upon restore, the compressed format is detected automatically.

false

System Properties

The following system properties for CRac can be set.

System Property Description Default Zing

System Property	Description	Default	Zing
jdk.crac.resource-policies=<value>	See File Descriptor Policies	null
jdk.crac.collect-fd-stacktraces=<true/false>	See Debugging Coordinated Restore at Checkpoint Failures > File Descriptors in Java Code	false
jdk.crac.trace-startup-time=<true/false>	Print startup time values to track how long the Java-side of the restore takes. This prints to stdout: `STARTUPTIME <SYSTEM NANOTIME> restore` `STARTUPTIME <SYSTEM NANOTIME> restore-finish`	false
jdk.crac.globalContext.impl=<value>	This property has two options: `OrderedContext` (default): Lets you register the resource when the checkpoint/restore is already executing, but this Resource’s `beforeCheckpoint()` and `afterRestore()` methods won’t be called during this checkpoint/restore. `BlockingOrderedContext`: Lets you assert that there is no new Resource registered during execution of the checkpoint/restore. The thread trying to register a new resource is blocked (this can lead to a deadlock).	OrderedContext
jdk.crac.enable-recompilation=<true/false>	Flag to define whether CRaC should record code decompiled during checkpoint/restore and schedule its recompilation afterwards. This can’t be changed after the first checkpoint starts. Disabling this may make JVM run a bit slower after the restore compared to before the checkpoint.	true	Not supported
jdk.crac.recompilation-delay-ms=<milliseconds>	If `jdk.crac.enable-recompilation` is true, this setting allows delaying finishing recording decompilations by the specified amount of time (values `<= 0` mean there will be no delay). Larger values allow more decompilations triggered by possible changes inflicted by checkpoint/restore to be recorded and recompiled but delay all other recompilations.	10	Not supported

jdk.crac.resource-policies=<value>

See File Descriptor Policies

null

jdk.crac.collect-fd-stacktraces=<true/false>

See Debugging Coordinated Restore at Checkpoint Failures > File Descriptors in Java Code

false

jdk.crac.trace-startup-time=<true/false>

Print startup time values to track how long the Java-side of the restore takes.

This prints to stdout:

STARTUPTIME <SYSTEM NANOTIME> restore
STARTUPTIME <SYSTEM NANOTIME> restore-finish

false

jdk.crac.globalContext.impl=<value>

This property has two options:

OrderedContext (default): Lets you register the resource when the checkpoint/restore is already executing, but this Resource’s beforeCheckpoint() and afterRestore() methods won’t be called during this checkpoint/restore.
BlockingOrderedContext: Lets you assert that there is no new Resource registered during execution of the checkpoint/restore. The thread trying to register a new resource is blocked (this can lead to a deadlock).

OrderedContext

jdk.crac.enable-recompilation=<true/false>

Flag to define whether CRaC should record code decompiled during checkpoint/restore and schedule its recompilation afterwards. This can’t be changed after the first checkpoint starts. Disabling this may make JVM run a bit slower after the restore compared to before the checkpoint.

true

Not supported

jdk.crac.recompilation-delay-ms=<milliseconds>

If jdk.crac.enable-recompilation is true, this setting allows delaying finishing recording decompilations by the specified amount of time (values <= 0 mean there will be no delay). Larger values allow more decompilations triggered by possible changes inflicted by checkpoint/restore to be recorded and recompiled but delay all other recompilations.

Not supported

Set these properties when you execute Java, for example:

 java -XX:CRaCCheckpointTo=... \
    -Djdk.crac.resource-policies=/path/to/file.yml \
    -jar my_app.jar arg1 arg2