Last updated on

Troubleshooting

This page lists some common problems you might encounter when setting up or using the tools for this course. For a guide on how to set up those tools, refer to the Tools Setup page.

Command Not Found

When running a command, be it code, coursier or any other one in your terminal, you may be greeted by a message similar to this:

// on Linux, macOS
-bash: code: command not found

// on Windows Terminal
code : The term 'code' is not recognized [...]

In such a case:

  1. Check whether you actually installed this program on your machine. If not, install it first. Follow the Tools Setup for the course if needed.

    If you are on Windows and using WSL, check that you are running the command in the environment where you installed the program.

    For example, if you install VSCode in WSL (Linux) , you will be able to run code . in the WSL terminal. If you then attempt to run code . in Windows PowerShell, the command will fail until you also install VSCode on Windows (outside of WSL).

  2. If the command is still not found, you might need to add the program to your PATH.

    • For Scala and SBT, re-run the installer as described in the Tools Setup and say y for “Yes” when the installer asks whether it should add Scala and SBT to the path.
    • For VSCode on MacOS, follow the official instructions.
    • For Git, the installer should have already added the program to your PATH by default.

  3. If you just installed the program, try closing and re-opening the terminal, or rebooting your machine. Some programs require this to be operational.

Curious about what the PATH environment variable is?

The PATH environment variable contains a sequence of directories on your system that your shell searches when looking for programs. Thanks to that, you can type scala in, e.g. scala -version command, instead of typing the full path to the Scala runner executable.

You can see your PATH environment variable by running:

$ echo $PATH  // on MacOS and Linux
$ echo %PATH% // on Windows Command Prompt
$ $Env:PATH   // on Windows Terminal, and yes, the second $ is part of the command

The paths will be separated by : or ; depending on your system.

IDE features like hover text, go-to-definition, or worksheets do not work

  1. Ensure that you launched code . from the right directory (the root folder of the exercise set or lab, which contains a .sbt file).

  2. Ensure that you imported the build: click on the “m” logo in the left bar, and then in the sidebar that appears, click on “Import build”, and then wait a bit.

  1. If things still don’t work, try restarting VS Code (launch it in the same way you started it before, using code . from the project directory). If you’re still having issues, try clicking on “Clean compile workspace” from the same sidebar.

Not a valid command, Expected X

When trying to run a command, for example code ., you might be greeted by a message similar to:

[error] Expected ID character
[error] Not a valid command: code (similar: oldshell, loadp)
[error] Expected project ID
[error] Expected configuration
[error] Expected ':'
[error] Expected key
[error] Not a valid key: code (similar: compile, console, clean)
[error] code .
[error]     ^

This means you tried to run a terminal command in an SBT context.

When you run sbt in your terminal, SBT does its thing and loads a few things, then your next terminal line might look something like this:

sbt:[project-name]>

where [project-name] is the name of the folder you ran sbt in. If you see this at the start of the line, it means you are in an SBT context, and the commands you run here will be processed by SBT, not by your system shell.

If you want to run a command such as code . or any other non-SBT command, you can either:

Neither build.sbt nor a project directory

When you get this error message:

[error] Neither build.sbt nor a 'project' directory in the current directory: /path/to/current/dir
[error] run 'sbt new', touch build.sbt, or run 'sbt --allow-empty'.

It means that you tried running sbt within a directory that is not an SBT project.

For example, it might be that you are trying to run SBT in the exercises directory, but the actual SBT project is in exercises/recursion, and thus you need to cd to the recursion exercise before running sbt.

SBT fails to start

If you see any kind of error when SBT starts that prevents you from using it, and if none of the other proposed SBT fixes work for your situation, follow those instructions as a last resort.

First, try cleaning the project cache by running:

$ git clean -Xdf

(To understand this command, consult the git clean documentation.)

Then, restart SBT. If this still doesn’t work, try deleting the global SBT cache:

SBT server could not start because there’s another instance

When trying to run sbt in one of your projects, you may see this message:

[warn] sbt server could not start because there's another instance of sbt running on this build.
[warn] Running multiple instances is unsupported

It means SBT is already running for this specific project somewhere on your machine. Try finding the other instance and use it instead of the new one you wanted to create, or stop it and re-launch sbt afterwards.

On Linux and macOS, you can stop it using

pkill -f sbt

On Windows, as a last resort, reboot your machine to stop SBT.

Import errors for external packages

Some of our labs use advanced features of SBT. If you try to do these labs with the default VS Code configuration, you may run into issues, such as missing completions or import errors. These issues will not prevent the code from compiling and running correctly, because they only concern the IDE support for Scala, not the project itself. IDE support is provided by software called Metals.

To fix these issues, you can ask Metals to talk to SBT directly, rather than using the default build tool (called “Bloop”). To do this just once:

  1. Press Ctrl+Shift+P (“Show All Commands”).
  2. Type “metals switch” and select the item “Metals: Switch build server”.
  3. When prompted, choose “SBT” instead of “Bloop”.

To make this switch permanent, you can either add "defaultBspToBuildTool": true to VS Code’s settings.json (at either the project level or for all projects), or click the gears icon to open the settings menu and search for “metals bsp” to find the corresponding setting in the UI.

Note: It’s not safe to run multiple copies of SBT in parallel. So, if you configure Metals to use SBT as above, then you cannot use sbt in the terminal to run your code, or start the tests. Instead, you must use sbt --client, which connects to the running copy of SBT started by Metals. If nothing appears when you type commands into SBT, try sbt -Djline.terminal=none --client instead.

Cannot run tests in VSCode

With Metals installed in VSCode, you might occasionally see a green “play” icon in the margin of the tests:

But sometimes, this icon is not present.

We do not provide support for this feature and we encourage you not to use it, for two reasons:

  1. The feature itself only works in simple cases. The more complex labs get throughout the semester, the more likely it is that you will have problems with it.

  2. Easy access to tests is not necessarily a good thing. Ideally, when having a problem with a test, you should apply the debugging method: think about the problem, understand why it occurs, correct your code, and pass the test. But if you can simply run the test using a button in VSCode, you might be tempted to perform random small changes in your code and run the test again and again until it passes. This does not lead to in-depth understanding.

Instead, we encourage you to use the sbt test command seen in the labs and exercises.

MacOS operation not permitted

When running commands in the terminal, you may get a message similar to the following:

This error usually means the Terminal does not have permission to access your files and folders (e.g. Downloads or Documents).

To fix this:

  1. Open the “System Settings” app
  2. Go to the “Privacy & Security” section
  3. Go to the “Files & Folders” menu.

In here, locate your terminal application (probably named “Terminal”) and allow access to the folders.

Last resort

If you’re still experiencing issues, check the output of sbt compile and sbt run, as well as the logs of the Metals extension in the file .metals/metals.log located inside your SBT project. If both of these resources don’t help resolve the problem, feel free to attend a lab or exercise session and ask a staff member for assistance, or make an Ed post with both pieces of information attached.

© 2023–2025 EPFL. All rights reserved.