corda/docs/source/troubleshooting.rst

Troubleshooting

Milestone releases

When you clone the corda or cordapp-template repos, they will default to the master branch. The master branch is being continuously developed upon, and its features may not align with the state of Corda as described in the docs. Additionally, the master branch of the CorDapp template may break in response to changes in the main corda repo.

When developing on Corda, you should always check out the latest milestone (i.e. stable) branch instead. For example, to check out milestone 0, you'd run git checkout release-M0.

Java issues

Outdated/non-Oracle JDKs

Many users have faced issues when running versions of Java that are either outdated, or are produced by organisations other than Oracle (e.g. OpenJDK). The errors generated by these issues will not always clearly point to the JDK as the cause. If in doubt, check your JDK version by following the instructions here. You can download the latest version of Oracle's JDK here.

"Unresolved reference: javafx"

JavaFX is not bundled with OpenJDK. If you are using OpenJDK and get an 'Unresolved reference: javafx' error, this means that you need to install OpenJFX.

If you have APT installed and OpenJFX is part of your Unix distribution's package list, you can do this by running sudo apt install openjfx, and possibly sudo apt install libopenjfx-jav. Other users will want to refer to the guide here, or to the list of Community Builds here.

"Check that you have the -parameters option specified in the Java compiler"

Some of the unit tests, and our serialization framework in general, rely on the constructor parameter names being visible to Java reflection. Make sure you have specified the -parameters option to the Java compiler. We attempt to set this globally for gradle and IntelliJ, but it's possible this option is not present in your environment for some reason.

IDEA issues

Fiber classes not instrumented

If you run JUnit tests that use flows then IntelliJ will use a default JVM command line of just -ea, which is insufficient. You will need to open the run config and change it to read -ea -javaagent:lib/quasar.jar and make sure the working directory is set to the root of the Corda repository. Alternatively, make sure you have the quasar.jar file in your application source tree and set the paths appropriately so the JVM can find it.

You can edit the default JUnit run config in the run configs window to avoid having to do this every time you pick a new test to run.

No source files are present

When opening a project in IDEA for the first time, you will need to build the project. You should see "Unlinked Gradle project?" in a pop-up window in the top-right corner or in a popup alert window. It will also appear in the "Event Log" window which can be opened by clicking on "Event Log" at the bottom right of the IDEA window. Find one of these links and click on "Import Gradle Project".

Wait for it to download the dependencies. You may then see another popup titled "Unindexed remote maven repositories found." This won't affect Corda, so you can choose to leave them unindexed.

If still have problems, the JetBrains website has more information on here.

Run configurations are missing

If you opened the Corda project by clicking "Import Project" on the IDEA splash screen rather than clicking "Open", a bug in IDEA will cause it to wipe and recreate the .idea directory where the run configurations are stored. The fix is simple and doesn't require you to re-import the project: just undelete the files! You can do that by either:

1. Running git checkout .idea/runConfigurations to redownload the files.
2. Using the "Version Control" pane in IDEA to undelete the files via the GUI.

IDEA complains about lack of an SDK

If IDEA refuses to open a project because an SDK has not been selected, you may need to fix the project structure. Do this by following these instructions. The correct JDK is often found on a path such as jdk1.8.0_xx…/Contents/Home. Ensure that you have the Project language level set at 8.

If you are having trouble selecting the correct JDK, the JetBrains website provides the following guidelines.

IDEA fails to compile Corda because it refuses to find some dependencies

First check that Corda compiles successfully from the command line using gradlew clean build. If this succeeds then IntelliJ may just have imported the project's Gradle files incorrectly. Try opening the

View/Tool Windows/Gradle

pane and clicking the "Refresh all Gradle projects" button. Then retry compiling Corda within IntelliJ. If this still fails then try

File/Invalidate Caches, Restart...

or checking the

Settings/Build,Execution,Deployment/Build Tools/Gradle/Runner/Delegate IDE build-run actions to gradle

checkbox, and then refreshing Gradle again.

IDEA fails to compile in VaultSchemaTest.kt

Run gradlew kaptKotlin to generate the sources IntelliJ is missing.

Kotlin plugin

There are two ways to configure Kotlin in IDEA:

1. Via the initial project opening screen, by using the Configure > Plugins tab.
2. From an open IDEA project, by clicking IDEA -> Preferences ... (on OS X) or File -> Settings (on Windows). Select the Plugins bar to confirm that Kotlin is installed and up-to-date.

If you are still having trouble installing Kotlin, first try upgrading the Kotlin plugin. At the time of writing, you can identify the latest version of the Kotlin plugin on this page.

"Unable to make the module: related gradle configuration was not found. Please, re-import the Gradle project and try again"

This can usually be solved by updating IDEA. Check that you have the latest version here.

"Check that you have the -parameters option specified in the Java compiler"

See entry under Java (above).

Other common issues

Slow localhost resolution

Out of the box, Apple Macs have machine names that end in ".local", by default something like "MacBook-Pro.local". This can cause long delays with starting Corda nodes as every attempt to look up the name of the local computer triggers a five second pause. This is not a bug in Corda but rather a problem with the macOS networking stack.

To fix it, you will need to use the Terminal app and edit your /etc/hosts file. For instance, you can do this by typing:

sudo nano /etc/hosts

then typing in your own password, assuming you are an administrator user of the computer.

You will need to ensure there are two lines for the name of your machine (which you can find in the Sharing section of System Preferences), which look like this:

127.0.0.1 MacBook-Pro.local fe80::1%lo0 MacBook-Pro.local

If you've changed the name of your computer in Sharing or via the hostname command, obviously ensure you replace MacBook-Pro.local with the correct name. Then press Ctrl-O to save the file and Ctrl-X to exit.

“xterm: command not found”

On some machines, running the samples requires xterm. You can download it here.