GitHub
DocumentationTroubleshooting

Reference

Troubleshooting

When something does not work, cstudy doctor usually says why and how to fix it. This page collects its common rows, the errors you are most likely to meet, and how to upgrade.

On this page
  1. Start with cstudy doctor
  2. Common errors
  3. Editor problems
  4. Several installs of cstudy
  5. Upgrading

Start with cstudy doctor

Most problems show up in cstudy doctor. Run it inside your workspace: each line is ok, WARN (not blocking) or FAIL (blocks practice), followed by a fix: when one applies. Many fixes are cstudy doctor --fix, which writes missing template files and sets up the projects without touching your own files.

Common cstudy doctor rows and their fixes
RowStatusFix
python/.venv missingFAILcstudy doctor --fix
typescript/node_modulesFAILcstudy doctor --fix
workspace filesFAILcstudy doctor --fix writes the missing files
runner runtimeFAILMissing or stale, typically after an upgrade: cstudy doctor --fix
javaFAILNot version 21: install a JDK 21 and make it the default (JDK 21)
go and rust filesWARNA workspace created before Go and Rust: cstudy doctor --fix
python debugpyWARNuv add --dev debugpy --directory python
python pytestWARNuv add --dev pytest --directory python; only Python project problems need it
project linksWARNcstudy doctor --fix recreates the links
rust linked projectsWARNcstudy ide
java project librariesWARNcstudy doctor --fix, online once
python/.venv locationWARNThe workspace moved: rm -rf python/.venv && cstudy doctor --fix
go, rustc, cargoWARNOnly needed for --lang go and --lang rust; see Installation
dlv, debugserverWARNOnly needed for --debug in Go and Rust

cstudy doctor exits 0 when nothing fails and 4 otherwise, so you can use it in scripts.

Common errors

Errors and what to do
MessageWhat to do
open a solution file in the editor first (got a directory: …)IntelliJ passed the project directory because no editor had focus. Click into your solution file and run the configuration again
not a solution file in this workspace: …The path is not where cstudy writes solutions. Use the file cstudy start printed, or the slug
go was not found on PATHInstall Go 1.24 or newer, or practise in another language. The same goes for cargo and Rust
level 3 is locked; pass level 2 with cstudy test firstPass the open levels before running a later one with --level
cstudy hint is locked during the mock interview (…)Hints and solutions unlock when the mock’s timer ends or every problem is done
cannot debug python: port 5678 on 127.0.0.1 is already in useStop the other debug session, or choose another port with --debug-port
no debugger listening on 127.0.0.1:5005With --debug-connect, start IntelliJ’s Debug JVM (listen) configuration first
cannot debug go: dlv was not foundgo install github.com/go-delve/delve/cmd/[email protected]
cannot debug rust: debugserver was not foundxcode-select --install

Commands that need a workspace exit with code 3 outside one and point you to cstudy init. Commands that act on the active attempt exit 3 when no attempt is in progress: start one, or name the problem.

Editor problems

  • No Python interpreter in VS Code: run cstudy doctor --fix so python/.venv exists, then reload the window.
  • rust-analyzer reports an outdated toolchain, or flags todo! and vec!: run rustup update.
  • A new Rust project problem is not analysed: run cstudy ide to add it to rust-analyzer’s linked projects.
  • IntelliJ shows no JDK: accept its prompt to set up the SDK named 21, then Load Gradle Project.
  • Kotlin breakpoints never hit in VS Code: the Java debugger does not bind them. Debug Kotlin in IntelliJ IDEA.
  • Your edited editor files were not updated: cstudy ide keeps files you changed and names them; cstudy ide --force overwrites them.

Several installs of cstudy

When cstudy is installed more than once, say with Homebrew and with uv, the one that comes first on your PATH runs. List them and keep one:

shell
which -a cstudy
cstudy --version

Upgrading

Upgrade with the tool you installed with, then refresh each workspace:

shell
brew upgrade cstudy              # or: uv tool upgrade coding-study / pipx upgrade coding-study
cd ~/cstudy-workspace
cstudy export                    # optional: a backup of your progress
cstudy doctor --fix              # refreshes the runner runtime, adds new template files
cstudy ide                       # brings the editor files up to date

cstudy doctor --fix never overwrites a file you have. Problems added in a new release join the catalog on their own. If a new catalog problem uses the slug of one of your own problems, yours keeps winning.

On a new machine

Clone your workspace, install cstudy and the toolchains, run cstudy doctor --fix in the workspace, then cstudy import to restore the progress you exported.

Release notes are in the changelog.

Written for cstudy 0.8.0. The specs in the cstudy repository are the source of truth for every detail.