Last updated on Thursday, October 16, 2025

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.

$ 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

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

When you open an assignment in VSCode for the first time, Metals will show a pop-up window:

Click “Import build” to turn on IDE support: this must be done for each new assignment or project. The IDE setup is not finished if, on the VSCode bottom-left corner, you can see that the build server (bloop or sbt) is still running or Metals is indexing:

Wait until the import process is complete to start coding.

If there is no popup

Confirm that you opened the correct folder in VSCode. You must open the root folder of the exercise set or lab, which contains a .sbt file. For example, opening exercises instead of exercises/recursion will cause Metals not to work.

If you opened the wrong folder, close VSCode, navigate to the right directory in the terminal, run code . from there, and look out for a popup.

If there’s still no pop up, or nothing happens after 30 seconds, you can click the Metals button with the “m” logo in the left panel, then click “Import build” in the Metals sidebar that appears:

If manually importing the build doesn’t help

Fix all compilation errors: Metals and worksheets will not work well (or at all) if your project contains compilation errors. Run sbt compile on the command line to see whether there are any compilation errors.

Once all errors are fixed, click the Metals icon in the left panel of VSCode, then click “Clean and restart build server” in the Metals menu, then wait for Metals to import the build. If this does not help, try “Clean compile workspace” instead.

If fixing build errors doesn’t help

1. Restart VSCode (launch it in the same way you started it before, using code . from the project directory).

2. Click Switch build server in the Metals menu to switch to the other build server (bloop or sbt), and wait for Metals to import the build. Check for compilation errors, and rerun the “clean” steps above if any unexpected errors pop up.

3. Close all applications, save your project files to a backup folder, then re-clone a fresh copy of the course-provided repository.

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:

• Open another terminal and run it there
• Close SBT in the current terminal by typing exit then Enter or pressing “Ctrl + D”.

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:

• On Windows, navigate to C:\Users\%USERNAME% and delete the .sbt folder.

• On GNU/Linux or macOS:

  $ cd ~
  $ rm -r .sbt
  

  Make sure not to put any spaces in the ~/.sbt path. To see the documentation of rm, try the command man rm.

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.

If Metals asks to turn off the old server and start a newer one

For example, if you first open exercises in VSCode and start Metals, then realize you are using the wrong folder and open exercises/<name> instead, you may see a popup window like this (with different version numbers):

It is normal. Click “Turn off old server” and a newer build server will start.

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.

If you use the test debugger but it does not stop at breakpoints

You’re on your own: we do not provide support for VSCode’s debugger.

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.

Weird characters appear in terminal on Windows

Encoding issues may cause your terminal to print unexpected symbols (“Mojibake”) instead of “special” (non-English) characters.

For example, if you are on Windows running the degrees lab with the command run 20 f within sbt, you may see something like:

There are two possible solutions: one local (applies only to the current terminal) that you will need to perform each time you open a new terminal, and one in the system settings.

First Solution (local)

This first solution only works for the Windows Command Prompt or in a PowerShell terminal. It will not work in a WSL terminal or in Git Bash.

Make sure to close SBT first, then run this command in your terminal:

$ chcp 65001

This will make your terminal use UTF-8 as a text encoding (see below to learn more about the issue). Try running sbt again, then re-running the problematic command, and check that the issue is gone.

Be aware that with this solution, you must re-run the above command every time you open a new terminal.

Second Solution (global)

For the second solution:

1. Press “Windows + R”.

2. Type intl.cpl inside the box that pops up, then press Enter or click OK.

   

3. The following window will open. Click on Administrative then Change system locale...

   

4. In the new window that pops up, check the Beta: Use Unicode UTF-8 for worldwide language support box.

   

5. Click OK, then restart your computer. The changes will not take effect until the computer is restarted.

After this, the problem should be fixed. Test it out by running the same command that gave you weird characters before. For example, running run 20 f within sbt in the degrees lab should output:

Cannot access the web interface for the lab

Some labs come with a web interface that you normally open by running sbt, run and then going to http://localhost:8080 in your browser.

In some cases, your browser may display an error message instead of the page. This will almost certainly happen if you run your lab within WSL, but it may happen in other rare cases.

The error message looks like this on Chromium-based browsers:

This page isn’t working
localhost didn’t send any data.
ERR_EMPTY_RESPONSE

and like this on Firefox-based browsers:

Unable to connect
<browser name> can't establish a connection to the server at localhost:8080

To fix it, follow the instructions to run the web UI once again (those can vary from lab to lab). They all have one thing in common: you need to run sbt at some point. When you do, instead of simply running sbt, you will need to run

$ CS214_HOST=0.0.0.0 sbt

This will start sbt as you normally would, except it tells the server to behave differently.

Follow the rest of the instructions, and the web interface should be reachable from your browser.

If the fix above worked for you but you do not want to re-type CS214_HOST=0.0.0.0 sbt every time:

1. In VSCode, press “Ctrl + Shift + F” (on Windows) or “Cmd + Shift + F” (on macOS). This will enable you to search through all the files of the current project. In IntelliJ, you can do the same by double-pressing Shift.
2. Search for 127.0.0.1.
3. Replace the place where you found 127.0.0.1 with 0.0.0.0. There should be only one.
4. Save the file (done automatically in IntelliJ, or if you have auto-save in VSCode).
5. Follow the instructions to access the web interface once again. With this change, you should only need to run sbt instead of the full CS214_HOST=0.0.0.0 sbt.

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.