The neo4j.conf file

The neo4j.conf file is the main source of configuration settings in Neo4j and includes the mappings of configuration setting keys to values. The location of the neo4j.conf file in the different configurations of Neo4j is listed in Default file locations.

Most of the configuration settings in the neo4j.conf file apply directly to Neo4j itself, but there are also other settings related to the Java Runtime (the JVM) on which Neo4j runs. For more information, see the JVM specific configuration settings. Many of the configuration settings are also used by neo4j launcher scripts.

neo4j.conf conventions

The syntax in the neo4j.conf file follows the following conventions:

  • The equals sign (=) maps configuration setting keys to configuration values.

  • Lines that start with the number sign (#) are handled as comments.

  • Trailing comments are not supported.

  • Empty lines are ignored.

  • Configuring a setting in neo4j.conf overwrites any default values. If you want to amend the default values with custom ones, you must explicitly list the default values along with the new ones.

  • The configuration settings are not ordered.

  • The configuration settings have strict validation enabled by default. It prevents Neo4j from starting if the neo4j.conf file contains typos, incorrect information, or duplicates (except for server.jvm.additional). If you set more than one value for server.jvm.additional, each setting value adds another custom JVM argument to the java launcher.

    To disable the strict validation, set server.config.strict_validation.enabled=false.

  • By default, the character encoding is assumed to be ISO 8859-1 but can be overridden by setting the environment variable NEO4J_CONFIG_FILE_CHARSET to, for example, utf8.

Configuration settings

General synopsis

Neo4j configuration settings have the following general synopsis:

<prefix>.<scope>.<component>…​.<component>.<name>

Prefix

Prefixes are reserved for denoting two special cases (most settings do not have a prefix):

  • initial — Settings that are only used during the initialization but are ignored thereafter. For example, initial.server.mode_constraint, initial.dbms.default_database, etc.

  • internal — The prefix replaces the terms unsupported and experimental used in previous versions. This namespace is dedicated to features that are used internally and may change without notice.

Scope

All configuration settings fall into one of the following scopes that behave differently:

  • db settings can be varied between each database but must be consistent across all configuration files in a cluster/DBMS.

  • dbms settings must be consistent across all configuration files in a cluster/DBMS.

  • server settings apply only to the specific server and can be varied between configuration files across a cluster/DBMS.

  • browser settings apply only to Neo4j Browser.

  • client settings apply only to the client.

Component

Component namespaces are used to group settings that affect similar systems.

Name

The name of the setting. It may contain a common verb and unit patterns, such as size, enabled, etc. Words are separated by an underscore.

For a complete reference of Neo4j configuration settings, see Configuration settings.

JVM-specific configuration settings

A Java virtual machine (JVM) is a virtual machine that enables a computer to run Java programs and programs written in other languages that are also compiled in Java bytecode. The Java heap is where the objects of a Java program live. Depending on the JVM implementation, the JVM heap size often determines how and for how long time the virtual machine performs garbage collection.

Table 1. JVM-specific settings
Setting Description

server.memory.heap.initial_size

Sets the initial heap size for the JVM. By default, the JVM heap size is calculated based on the available system resources.

server.memory.heap.max_size

Sets the maximum size of the heap for the JVM. By default, the maximum JVM heap size is calculated based on the available system resources.

server.jvm.additional

Sets additional options for the JVM. The options are set as a string and can vary depending on JVM implementation.

If you want to have good control of the system behavior, it is recommended to set the heap size parameters to the same value to avoid unwanted full garbage collection pauses.

Neo4j comes with several pre-defined values of the server.jvm.additional setting. You can find them in the neo4j.conf file. The table below lists them and explains their roles.

Table 2. Pre-defined values of server.jvm.additional
Default value Note

server.jvm.additional=-XX:+UseG1GC

G1GC (Garbage-First Garbage Collector) provides a good balance between throughput and tail latency with minimal tuning requirements.

server.jvm.additional=-XX:-OmitStackTraceInFastThrow

Ensures that common exceptions always have stack traces, allowing effective debugging regardless of logs rotation frequency.

server.jvm.additional=-XX:+AlwaysPreTouch

Ensures that initmemory is not only allocated but also committed to the process before the database starts. It is recommended to reduce the heap memory if this flag degrades performance.

server.jvm.additional=-XX:+UnlockExperimentalVMOptions

Trusts that non-static final fields are really final. This allows more optimizations and improves overall performance. Disable this flag if you use embedded mode or have extensions or dependencies that may use reflection or serialization to change the value of final fields.

server.jvm.additional=-XX:+TrustFinalNonStaticFields

server.jvm.additional=-XX:+DisableExplicitGC

Disables explicit garbage collection, which is occasionally invoked by the JDK itself.

server.jvm.additional=-XX:-RestrictContended

Allows Neo4j to use @Contended annotation.

server.jvm.additional=-Djdk.nio.maxCachedBufferSize=1024

Restricts size of cached JDK buffers to 1 KB.

server.jvm.additional=-Dio.netty.tryReflectionSetAccessible=true

Enables Netty to allocate direct buffers more efficiently by allowing reflection-based access to internal JVM APIs. This bypasses the standard JVM cleanup mechanism.

server.jvm.additional=-Dio.netty.leakDetection.level=DISABLED

Netty resources leak detection. Possible values are DISABLED, SIMPLE, ADVANCED, and PARANOID. Ignores case. For more details refer to the Netty documentation.

server.jvm.additional=-Djdk.tls.ephemeralDHKeySize=2048

Expands Diffie Hellman (DH) key size from default 1024 to 2048 for DH-RSA cipher suites used in server TLS handshakes. This is to protect the server from any potential passive eavesdropping.

server.jvm.additional=-Djdk.tls.rejectClientInitiatedRenegotiation=true

Mitigates a DDoS vector.

server.jvm.additional=-XX:FlightRecorderOptions=stackdepth=256

Increases the default flight recorder stack sampling depth from 64 to 256, to avoid truncating frames when profiling.

server.jvm.additional=-XX:+UnlockDiagnosticVMOptions

Allows profilers to sample between safepoints. Without this, sampling profilers may produce less accurate results.

server.jvm.additional=-XX:+DebugNonSafepoints

server.jvm.additional=--add-opens=java.base/java.nio=ALL-UNNAMED

Opens modules for Neo4j to allow internal access.

server.jvm.additional=--add-opens=java.base/java.io=ALL-UNNAMED

server.jvm.additional=--add-opens=java.base/sun.nio.ch=ALL-UNNAMED

server.jvm.additional=--add-opens=java.base/java.util.concurrent=ALL-UNNAMED

server.jvm.additional=--enable-native-access=ALL-UNNAMED

Enables native memory access.

server.jvm.additional=-Dlog4j2.disable.jmx=true

Disables logging JMX endpoint.

server.jvm.additional=-Dlog4j.layout.jsonTemplate.maxStringLength=32768

Increases the JSON log string maximum length.

List currently active settings

You can use SHOW SETTINGS to list the currently active configuration settings and their values.

Example 1. List currently active configuration settings
SHOW SETTINGS
YIELD name, value
WHERE name STARTS WITH 'server.default'
RETURN name, value
ORDER BY name
LIMIT 3;
+---------------------------------------------------+
| name                                | value       |
+---------------------------------------------------+
| "server.default_advertised_address" | "localhost" |
| "server.default_listen_address"     | "localhost" |
+---------------------------------------------------+

For information about dynamic settings, see Update dynamic settings and Configuration settings reference.