---
schema_version: "1"
id: c3dc641162a3b6ccb79f0f818a3adc7eeaf49bd7151fb557c00eb7fbbd29c359
title: Upgrading and Migrating Neo4j Connector to Version 4.0.0
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/neo4j-connector/latest/neo4j-connector-upgrade-migrate.md
canonical_url: https://docs.mulesoft.com/neo4j-connector/latest/neo4j-connector-upgrade-migrate
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 658a5a463e39b591dcfaadda4b559dd751bdbcf025623bc54f39d79a856642a9
description: MuleSoft Documentation Site
release: "4.0"
latest: true
---
---
product: Neo4j Connector
version: 4.0
is-latest-version: true
---

# Upgrading and Migrating Neo4j Connector to Version 4.0.0

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

Upgrade Anypoint Connector for Neo4j (Neo4j Connector) to version 4.0.0.

## Supported Upgrade Paths

<table><colgroup><col> <col></colgroup><thead><tr><th>From Version</th><th>To Version</th></tr></thead><tbody><tr><td><div><div><p>3.0.x</p></div></div></td><td><div><div><p>4.0.0</p></div></div></td></tr></tbody></table>

## Changes in This Release

This release contains significant changes:

- Upgraded the Neo4j Java driver from version 1.7.6 to 5.28.8.

- Updated Neo4j server requirements to version 4.4 and later (previously supported Neo4j 3.x).

- Required minimum JDK 17 (upgraded from JDK 8).

- Updated minimum Mule runtime engine (Mule) to 4.9.0 (upgraded from 4.1.x).

- Removed the **REST URL** parameter from the connector configuration.

- Overhauled input and output metadata resolution for a better Anypoint Studio experience.

- Provided full compatibility with Neo4j 5.x and 2025.x server features.

- Gained access to reactive APIs, multi-database support, and enhanced security.

- Updated Docker configuration settings to use current Neo4j standards.

- Changed the connector to only require a BOLT URL configuration.

- Changed all metadata operations to use native Cypher queries through a BOLT connection instead of
  REST API calls.

## Requirements

Ensure that you meet these requirements before you perform the upgrade.

### Neo4j Server Requirements

- The minimum Neo4j server version required is 4.4 LTS or later.

- The recommended versions are Neo4j 5.26 LTS or Neo4j 2025.06+.

- Neo4j 3.x servers are no longer supported.

### Java Runtime Requirements

- The minimum JDK version required is 17

- The only supported JDK version is 17

- JDK 8 and 11 are no longer supported

### Mule Requirements

- Minimum Mule version 4.9.0, required for JDK 17 support and unified connectors parent
  compatibility

- Mule versions 4.1.x - 4.8.x not supported

### Development Environment

- Anypoint Studio latest version supporting Mule Runtime 4.9.0+

- Maven version supporting JDK 17+

## Considerations

Before you perform the upgrade, be aware of these known limitations:

- Restore from backup to roll back after upgrading the connector.

- Avoid using Neo4j 3.x servers with connector version 4.0.0.

- Ensure Mule applications run on Mule 4.9.0+ and JDK 17+.

- Update existing configurations that use the REST URL parameter.

- Re-test all existing connections after upgrading the connector.

- Refresh Studio metadata for the connector operations.

- Upgrade test servers to Neo4j version 4.4+ before performing connector testing.

- Use a JDK 17+ toolchain for Maven builds.

## Upgrade Prerequisites

Before you perform the upgrade, you must complete the following.

### Prepare Your Environment

1.  Create a backup of your Mule applications, data, and configurations

2.  Upgrade Neo4j Server to version 4.4 LTS or later (if currently using Neo4j 3.x)

3.  Upgrade Mule to version 4.9.0 or higher

4.  Upgrade JDK to version 17 or higher on all environments (development, test, production)

### Asses Mule Application

1.  Review existing configurations to identify REST URL usage.

2.  Document current BOLT URL settings for post-upgrade validation.

3.  Test connectivity to make sure Neo4j servers are accessible via BOLT protocol.

4.  Identify custom error handling that references connector-specific error types.

## Upgrade the Connector in Anypoint Code Builder

Follow these steps to perform the upgrade:

1.  In **Explorer**, right-click the configuration XML file in your integration project, and select
    **Project Properties**.

2.  In **Project Properties**, select **Connectors**.

3.  Select the latest version for the connector, and click **Apply**.

## Upgrade the Connector in Studio

Follow these steps to perform the upgrade:

1.  In Anypoint Studio, open your existing Mule project.

2.  In **Mule Palette**, click **Search in Exchange**.

3.  In **Add Dependencies to Project**, enter `neo4j` in the search field.

4.  In **Available modules**, select **Neo4j Connector** and click **Add**.

5.  Click **Finish**.

6.  Verify that the Neo4j Connector `<dependency>` version is `4.0.0` in the `pom.xml` file in the
    Mule project:

    ```xml
    <dependency>
      <groupId>com.mulesoft.connectors</groupId>
      <artifactId>mule-neo4j-connector</artifactId>
      <version>4.0.0</version>
      <classifier>mule-plugin</classifier>
    </dependency>
    ```

Studio upgrades the connector automatically, but configuration changes are required.

## Post Upgrade Steps

After you install the latest version of the connector, follow these steps to complete the upgrade:

### Remove REST URL Parameter

The REST URL parameter is no longer supported in the connector configuration. Update your
configurations:

Before (Version 3.x):

```xml
<neo4j:config name="Neo4j_Config" doc:name="Neo4j Config">
    <neo4j:connection username="${config.username}"
                     password="${config.password}"
                     boltUrl="${config.boltUrl}"
                     restUrl="${config.restUrl}" />
</neo4j:config>
```

After (Version 4.0.0):

```xml
<neo4j:config name="Neo4j_Config" doc:name="Neo4j Config">
    <neo4j:connection username="${config.username}"
                     password="${config.password}"
                     boltUrl="${config.boltUrl}" />
</neo4j:config>
```

### Update Connection Properties

Remove the REST URL property from your configuration files:

Before:

```text
config.username=<USERNAME>
config.password=<PASSWORD>
config.boltUrl=<BOLT_URL_ENDPOINT>
config.restUrl=<REST_URL_ENDPOINT>  <!-- Remove this line -->
```

After:

```text
config.username=<USERNAME>
config.password=<PASSWORD>
config.boltUrl=<BOLT_URL_ENDPOINT>
```

### Update Runtime Environment

1.  Make sure all environments are running on Mule 4.9.0+.

2.  Verify all environments are using JDK 17+.

3.  Make sure Neo4j servers are version 4.4+ or 5.x.

### Refresh Metadata

1.  Regenerate metadata in Anypoint Studio for improved design-time experience.

2.  Test the connector operations to ensure metadata is properly resolved.

3.  Validate the DataWeave expressions benefit from enhanced type information.

### Verify the Upgrade

After you install the latest version of the connector, verify the upgrade:

1.  Make sure no REST URL references remain in configurations.

2.  Verify the `pom.xml` file shows version 4.0.0 of the Neo4j Connector.

3.  Use the **Test Connection** feature to validate BOLT connectivity.

4.  Check that the operations show comprehensive field suggestions in Studio.

5.  Execute existing unit tests to ensure functionality is preserved.

6.  Verify no deprecation warnings appear during application startup.

## Troubleshooting

If you encounter issues, perform these troubleshooting ste\[s\].

### Troubleshoot Connection Failures After Upgrade

If the connector cannot connect to Neo4j server after upgrade, follow these steps:

1.  Verify that the Neo4j server is version 4.4+ (Neo4j 3.x is no longer supported).

2.  Make sure the BOLT protocol is enabled on Neo4j server.

3.  Remove any REST URL references from the configuration.

Error example:  
`Neo4j.ClientError.Security.Unauthorized`

Therefore, verify credentials and server accessibility via BOLT port (default 7687).

### Troubleshoot Metadata Not Displaying in Studio

If the connector operations show empty metadata or missing field suggestions, try these steps to
solve the issue:

1.  Ensure sample data exists in your Neo4j database for the labels you’re using.

2.  Regenerate metadata by refreshing the connector in Studio.

3.  Verify the BOLT connection is working properly.

### Troubleshoot Runtime Compatibility Issues

If the Mule application fails to start with JDK or Mule runtime errors, try these steps:

1.  Upgrade to JDK 17+ (JDK 8/11 no longer supported).

2.  Upgrade to Mule Runtime 4.9.0+ (earlier versions incompatible).

3.  Update Maven build configuration for JDK 17 compatibility.

### Revert the Upgrade

If you need to revert to the previous version of Neo4j Connector, go to Anypoint Studio and in the
project’s `pom.xml` file, change the `mule-neo4j-connector` dependency version 3.0.0 to the previous
version.

> [!IMPORTANT] Reverting requires restoring to environments compatible with version 3.x
> requirements.

## See Also

- [Introduction to Anypoint Connectors](https://docs.mulesoft.com/connectors/introduction/introduction-to-anypoint-connectors)

- [Salesforce Help](https://help.salesforce.com)