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

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, three plugins 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.

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.

What about the local Gradle build? The tests can be executed locally with ./gradlew ant-build-tests -Dmps.home=PATH_TO_YOU_MPS_INSTALLTION. The test results can be found in build/iets3-allScripts ( IETS3 ⧉).

  • If it runs (green), then there is a discrepancy between the CI and your local Gradle build.
    • Make sure you are on the same branch/commit as the CI,
  • If it shows the same test failures as the CI, then there is a discrepancy between the MPS Build and the Gradle Build.
    • Rebuild the build scripts in MPS.
    • Try running the tests in a separate process (edit the run configuration in MPS).
    • Make sure your MPS uses the same (versions of the) dependencies as the gradle build.
      • This can be achieved in 2 different ways:
        • Run ./gradlew dependencies to see which versions of which dependency gradle uses and make sure the OS and Mbeddr repos are checked out on the right branches/commits ( IETS3 ⧉).
        • Remove the file projectlibraries.overrides.properties from your repo and execute ./gradlew setup in both. This configures MPS to directly use the Java class files from the Gradle artifacts instead of the checked-out repos.

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.
Last update: November 7, 2023

Comments