Skip to content

Troubleshooting guide

This is a non-exhaustive list of common problems with MPS and platform projects. It is assumed that Gradle is used for building the project. For general MPS problems, read Finding your way out ⧉ first. If you are still stuck with your problem, read overcoming obstacles next.

MPS and MPS Platforms

The following questions assume that you use Gradle to build your project. The README file of your project should have more information about common issues and how to build the project.

When you build an MPS project, it can make a big difference between removing all generated files first and building the project (clean build), or skipping the first step (dirty build). When doing CI, you have to do a clean build or certain kind of errors can't be detected.

For checking out a different branch, a dirty build or rebuilding the languages manually can be the faster option. When you didn't do any generator changes or other changes that require a rebuild, calling make on the changed languages can be even enough.

Which type of build you choose is up to you and highly depends on the project. Experience with it in your team, and compare if the risky dirty build is worth the time you save.

The IDE is sluggish and doesn't work the way it should.

Edit the file mps(64).vmoptions and give it sufficient heap space: -Xmx8g Make sure that the issue is not caused by any of the used languages. You can also enable the power save mode through File → Power Save Mode to disable all background tasks including file indexing and typesystem checking. This approach also helps to see if an issue is related to a slow typesystem check or if there is a performance issue in the editor.

MPS behaves strangely 🔰

For instance: claims that a method is missing, although it exists.

  1. Check if you have mixed dependencies for different MPS versions or are opening the project with the wrong MPS version.
  2. Tools → Reload All Classes.
  3. File → Invalidate Caches, then restart.
  4. File → Invalidate Caches, shutdown MPS; in the repository in question: run git clean -fxd -e build.properties -e gradle.properties, rebuild with Gradle (./gradlew), restart MPS.

Try invalidating the cache ⧉ and check what other non-MPS plugins you have installed. Some IntelliJ plugins that can be found on the marketplace can interfere with MPS plugins, for example, make the indexing break or throw errors because they expect a text editor and not the projectional editor from MPS. Firewalls and proxies ⧉ could also affect MPS negatively.

MPS freezes on startup.

There can be multiple reasons for freezes at startup:

  • an infinite loop in an application/project plugin
  • wrong usage of threading mechanisms that lead to a deadlock ⧉.
  • the startup module maker compiles not built modules
  • a deadlock occurs because some code interferes with indexing ⧉ files

If you know the offending module/model, the simplest solution is to delete the generated files in the file explorer (source_gen/classes_gen). Then fix the error and recompile the module/module.When you are unsure where the error comes from, you can do remote debugging ⧉. There is also the dontReopenProjects command line flag to not open the last project when starting MPS. It helps to access the general settings or to remove plugins.

MPS cannot find languages/solutions.

For instance: "language X is not deployed" errors.

  1. File → Invalidate Caches, shutdown MPS.
  2. Run ./gradlew setup --refresh-dependencies.
  3. Start MPS again.

There could also be some other reasons:

  • A wrong version of the platform is used, for example, MPS Extensions ⧉ 2021.1 with MPS 2021.2. The major and minor versions have to be the same. Bug fix versions (e.g., 2021.1.4) should be compatible with the major/minor version of the platform. In rare cases, there can be an incompatibility because a bugfix/feature was backported from a newer MPS version, and the change is a breaking change.
  • Make sure that MPS is started with the correct Java version (execute the Choose Boot Runtime for the IDE action) and check that the bundled JBR or an external JBR/JRE is used. Another runtime could be selected by accident (e.g., a GraalVM ⧉ runtime)
  • If you want to use JCEF ⧉, it must be a JBR runtime that includes JCEF.
  • An MPS plugin was disabled (e.g., Java Debugger for MPS) that a language depends on.
  • For mbeddr, one plugin need to be installed ⧉ to avoid languages that can't be loaded because they have dependencies on one of the three plugins.

The IDE doesn't let you enter some text / an intention isn't visible that should be there.

  1. Check: Was the intention disabled by the user by accident?

example:disable an intention

In this case, the intention can be enabled through preferences → MPS intentions and manually searching for the disabled intention:

preferences menu:MPS intentions

  1. Check: Is the concept/intention visible in the model? (open a context menu where Base Language code is allowed and search for classes/concepts from the same language)
    • → Use Edit → Add Language Import to import the language containing the concept / the intention.
  2. Check the concept: Is the concept's type suitable for the place where you want to create an instance? Does it implement the right interface?
  3. Check the intention: Is the isApplicable() method called? (add a System.err.println() to the method and check what MPS outputs)
    • → The intention is most probably not visible in the model → see above
    • → Make sure the method returns true
  4. Concept: Does a constraint on one of the ancestor nodes prohibit you from creating it?

MPS build fails 🔰

  1. Does the MPS Model-Checker report problems? → Fix identified problems.
  2. Does the build log report intelligible problems? → Fix identified problems.
  3. Does it build in Gradle? → See: Gradle-Build fails.

MPS can't be started at all.

There could be multiple reasons:

  • One reason could be a wrong Java version. That could be a different Java runtime like the GraalVM or an incorrect Java version. MPS 2022.2 and newer need JDK 17, older ones need JDK 11, and ancient versions of MPS need JDK 8.
  • Through external changes, files of an MPS project could get deleted or corrupted by accident (such as deleting model files). There should be an exception that should give a hint of why the startup fails. The log file ⧉ should also contain an error message.

Basic MPS functionality stops working (e.g., typing doesn't work, the editor has an incorrect layout, or the window turns blank).

If you are not using one of the platforms, you should report the issue to the MPS issue tracker ⧉. Most of the bugs are caused by languages or plugins in MPS Extensions ⧉/ mbeddr platform ⧉.

For editor-related issues, try pressing F5 and check if the relayout method of the editor fixes the editor. If it does, report an issue in MPS Extensions ⧉. The most likely culprit is the cell layout ⧉ language. If another basic editor functionality like typing doesn't work anymore, the same language or another language in the same repository can cause such issues. For all other issues, check if a fatal error was thrown in the lower right corner.

Visit the issue tracker reference page to find the right issue tracker when you can't identify the repository based on the package name in the error message. Please don't just report the issue to the JetBrains MPS issue tracker ⧉ because the issue will likely be marked as invalid and doesn't land in the right issue tracker.

The MPS console shows the error message: java.lang.ClassNotFoundException: ConsoleModel_.Main

This exception can happen when you import a module/model into the console where the class loading fails, for example, because a dependency is missing, a language is not deployed/generated or the classloading is set to none. What you can try is to press the "clear" button in the console, import one language after another, and execute a simple expression like 1+1. When you have an issue with a language or dependency you will get this exception again. Another reason can be broken dependencies in a model that you import. Check the log file for additional hints. For the last reason, this can show up as a warning that the solution was marked invalid for classloading in the log file.

Some aspect descriptors like StructureAspectDescriptor can't be generated

Starting from MPS 2023.2, the corresponding devkit has to be import (in this case jetbrains.mps.devkit.aspect.structure. Unlikely but there could be also compilation issues while generating the aspect descriptor. If you the documentation descriptor for the documentation language can't be build, you are not using the documented concept/property annotation from com.mbeddr.doc.aspect in the documentation. This is needed for the descriptor to get generated.

Gradle

Gradle | Build gives some more details about working with this build tool. When working with Gradle, make sure that you know which versions you are using. Different Gradle versions support different Java versions. Another topic that often leads to syntax issue, is lazy configuration ⧉ which delay calculations until it's actually required.

Gradle build fails.

  1. Did you call git clean -fxd -e build.properties before ./gradlew? → Do it, retry.
  2. Did you call ./gradlew with --refresh-dependencies? → Retry with --refresh-dependencies.
  3. Does the error message start with: dependencies should be extracted into the build script?
    • In MPS, apply the model-checker to the "build"-package. Many problems can be fixed by applying the intention "Reload modules from disk."
    • Rebuild the "build"-package.
    • Retry the gradle build.
  4. Do you have local changes?
    • → Use git stash to stash them away and retry.
    • When the build works without your changes, then your changes are the problem. Redo them one by one to find the one that causes the problem.
  5. Does it work on CI?
    • → Is it a recent CI build?
      • → Retrigger via a whitespace-only commit.
      • → Search for differences between your local Gradle build and the CI build (versions).
    • → Is it the same error message?
      • → Search for differences between your local Gradle build and the CI build (versions).
    • Is the main build green on CI?
      • → Find out who broke it and make him fix it. After it is fixed, continue.
    • Is the main build recent?
      • → Retrigger it via a whitespace-only commit.
      • → Merge main into your branch and retry.
  6. If nothing helped: try cloning your repo again.
  7. You are out of options. Ask somebody for help.

CI

Tests are failing on CI but are green in the local MPS installation.

One reason can be that in the local MPS installation all necessary plugins are loaded or tests are executed in the same MPS instance. Especially starting from MPS 2024.1 all necessary plugins need to be declared in the build script, but also for executing tests.

Another common issue are flaky tests that don't always show the same behavior. There can be multiple reasons for that including timing issues or other issues related to multi-threaded code.

Make also sure to replicate the environment on the CI locally and run the tests from the command line if you can't see the failure in MPS itself.

More information can be found in: Why does my test fail when run from Ant but not when run from MPS? ⧉ (Specific Languages' blog)

Explanations

  • git clean -xdf
    • removes untracked files from the working tree (= also files generated by MPS)
    • x: Remove only files ignored by Git. This may be useful to rebuild everything from scratch but keep manually created files.
    • d: Remove untracked directories and untracked files.
    • f: If the Git configuration variable clean.requireForce is not set to false, git clean will refuse to delete files or directories unless given -f, -n or
    • e: Use the given exclude pattern besides the standard ignore rules.

Comments