Troubleshooting

This section attempts to address common issues that can occur when working with this toolchain.

Error 1: Project JDK is not defined

The first time you try and run Kotlin code in IntelliJ, it will likely complain that it cannot locate a Project JDK (i.e. Java JDK):

Project SDK Not Defined}

To fix this, click on Setup SDK, and choose one of the OpenJDK releases[^1].

In this example, we’re picking OpenJDK 16 using a popular build. Make sure to use the version number that matches the required version for this offering of the course.

After it’s installed, you should restart IntelliJ to make sure it picks up the changes.

JDK installation

Error 2: “Build” not available

Symptom: The Build action isn’t available.

Solution: Set the location of the source code.

IntelliJ needs to know what to consider the top-level of your source directory (it may seem obvious with a simple project, but complex projects may have a complicated directory structure).

In the Explorer pane on the left, right-click on the “src” folder. Choose “Mark Directory As…” and select “Sources Root”. It should then be selectable and the Main class.

You need to set source-root for IntelliJ to locate source files

You should be able to build the project at this stage (Build-Build Project).

Error 3: “Run” not available

Symptom: The Run icon in IntelliJ is disabled.

Solution: Make sure to build and run from the Gradle menu (View - Build Tools - Gradle) at least once successfully. This will enable the toolbar and menu shortcuts, which just call the last successful build and run commands.

Error 4: Missing classes

Symptom: Errors referring to missing components or classes. e.g. “Error: JavaFX runtime components are missing, and are required to run this application”.

Solution: Check that your build.gradle file is setup to import the required libraries. See Creating a New Project

Error 5: “Kotlin Not Configured”

Symptom: You open a project, and a banner at the top of the window shows this error (ed: your version number may be slightly different, that doesn’t matter).

Solution: Click on the Configure button, select Java.

When prompted, choose the default options and click OK.

create_kotlin_runtime

Error 6: Text not displayed properly

Symptom: You are attempting to display text in a JavaFX application and your text is garbled. font_bug

You also may see font errors in your output window. e.g.

2021-09-12 16:39:36.036 java[72697:3020563] CoreText note: Client requested name ".SFNS-Regular", it will get Times-Roman rather than the intended font. All system UI font access should be through proper APIs such as CTFontCreateUIFontForLanguage() or +[NSFont systemFontOfSize:].

This appears to be a bug with older versions of the JDK.

Recommended Solution: Use supported versions of JavaFX and OpenJDK – newer versions fixed this bug.

Workaround: This workaround also solves the problem: specify the font in your code.

val label = Label("Hello JavaFX")
label.font = Font("Helvetica", 14.0) // specifing the font fixes it!

Error 7: JavaFX program does not start

Symptom: You receive the error message

java.lang.module.FindException: Error reading module: [YOU MODULE NAME WILL BE REFERENCED HERE]
Caused by: java.lang.module.InvalidModuleDescriptorException: Package [YOU PACKAGE NAME WILL BE REFERENCED HERE] not found in module```

**Solution**: Make sure start your program using the Gradle script ``Tasks -> applicatin -> run`` and **not** just run the ``Current File``.

[^1]: All JDK distributions sharing a version number should have been built from the same source code and should behave identically for this course.