Troubleshooting

What each course needs installed, how to get unstuck, the failure messages you will actually see, and how to reset things when in doubt.

Toolchain prerequisites

sboot itself needs nothing installed — but the courses build real systems with real toolchains, on your machine. When a tool is missing, the grader does not start, nothing is recorded, and sboot names the missing tool and the install command for your OS. What each course uses:

On macOS the packages come from Homebrew (brew install nasm qemu xorriso), on Debian/Ubuntu from apt (sudo apt install nasm qemu-system-x86 xorriso build-essential). None of that is needed for rust-for-kernels.

Each course states its own requirements on its course page, and where a course has a lab 0, that lab is the checkable version: it runs the real loop on the untouched starter tree, so a green sboot test there means your toolchain is genuinely working before you write anything.

When a check fails: the ladder, then the chat

The first stop is always the failure evidence sboot test prints — it names what the check looked for and what it found instead, from your own run. A failing run ends by naming both of the next steps:

stuck?  sboot hint · https://sourceboot.com/courses/kernel-in-rust/stages/02-glass-cockpit#stuck

• sboot hint — where a course publishes hints, run it after a failing test. With no arguments it picks up the current lab and the first check your last run failed, and prints [hint 1 of N · <check-id>]; asking again for the same check goes one hint deeper, down to a step-by-step debug ladder. sboot hint <stage> <check-id> targets a specific check. If the build failed and no check ran, it starts from the compiler's first error, quoting it. Each later ask goes one hint deeper into what the lab has written about that error, and it says so when nothing has been written. The hints ship with the lab's tests, so it works offline. Online, it sends one line of usage data per hint (course, lab, check, depth, never your code, compiler output or paths). A course with no published hints says so and exits cleanly, and a check that already passes is not hinted.
• sboot explain — the step above the written hints, and it is a terminal command: the same check taken to the AI tutor with your last run's evidence already attached. By default it prints, and opens, the lab page's Stuck? chat with that check in the link — the chat lives there because it keeps context across turns and can render code. sboot explain --here answers in this terminal instead: one question, one streamed reply, no browser. Both need the network; the hint ladder does not.
• The lab page's Stuck? section mirrors the same ladder from the same authored source, one hint per click, and hosts that chat. It guides rather than hands over the answer. What the chat has left is shown beside its input and named again in the refusal if it runs out; the ladder above it spends nothing — sboot hint never even reaches the network.
• Layer 0 is always there. Whatever the course, a failing check in sboot test is followed by what your own run actually did. On os-rust the course additionally authors guidance under each failing check, and it digs deeper after three consecutive failures of the same one.

sboot reveal is the end of the ladder, on both surfaces — the control sits at the bottom of Stuck?, and the command does the same thing. It shows the course's own solution in two gated steps, and taking it marks that lab solution-assisted on your record: an annotation, which never blocks completing the lab and changes no score.

The guidance always points at your own code and your own evidence — it never paraphrases the answer.

Failures you may meet, in their own words

the platform did not accept your token (HTTP 401) — your credential is missing, stale, or from another deployment. Reconnect with sboot login, or paste a fresh token from /account into SBOOT_TOKEN. On a brand-new machine this is the expected first failure: the CLI's built-in default token only works for local development. sboot whoami tells you which credential is being used.

your stored login is for <other-url>, not <this-url> — not using it — you have connected this machine to a different deployment (a preview, a local platform). Run sboot login against the one you mean, or set SBOOT_TOKEN, which always wins.

no course workspace here — nothing to grade — you are outside a course repo. sboot courses lists them; sboot start <id> begins one; cd into the one you have.

this lab is not open to you yet / submission rejected (HTTP 403) — nothing is wrong with your setup. The lab is locked: either the previous lab is not completed yet (labs unlock in order, off the Complete button on its review page) or it is past your plan's free line. The site's course page shows which, and the way past it.

./kernel-sb already exists and is not empty — and it is not a SourceBoot workspace — the folder sboot start wanted is taken by something else. (The name is the course's own: <what you finish with>-sb — kernel-sb, word-game-sb — or the course id where a course names no such thing.) The refusal names both ways out, and changes nothing: unpack elsewhere with sboot start <course> --dir <name>, or, if that directory is your copy of this course from another machine, sboot resume <path>.

Running sboot start on a workspace that is ours for that course is not refused at all — it repairs. It re-fetches the scaffold, puts back only the paths that are missing, and prints what came back; a file you have edited is not compared, not backed up and not touched.

A build that never started vs a build that failed. If the message is <tool> is not installed (or is not on your PATH), the grader could not start — install the named tool; nothing was recorded. If you see your own compiler errors and then BUILD FAILED — fix the errors above and try again, the toolchain is fine and the errors are the lab. The two are deliberately kept distinct: a toolchain problem is never recorded as a failed practice run.

A kernel that hangs. A run that stops producing the expected output is cut off at the lab's boot timeout — about 12 seconds by default (a lab can set more) — and the checks that needed the missing output fail with the evidence collected up to that point. A hang is graded as what it is, not waited on forever.

no tests cached for <course> and the platform is unreachable — the first fetch of a lab's tests needs a connection. Connect once (or run sboot fetch while online, before travelling); after that, sboot test works offline.

Run sboot test <stage> first, then sboot hint picks up what failed — sboot hint reads the last run's verdict, so it needs one. Or name the check yourself: sboot hint <stage> <check-id>.

your work was uploaded, but nothing graded it — a problem on our side, not with your code; nothing about your submission was judged. Re-run the same sboot submit in a few minutes — a retry lands on the same submission rather than creating a second one. Twice in a row means the grading service is down; re-submitting will not help.

no review is stored for this submission on the Review tab — the submission predates the review flow, or its review row could not be created. The grade stands; submitting again gets a fresh review.

… tests need sboot X or newer — this is sboot Y — your CLI predates this course's tests. Run the printed install command; details in the CLI reference.

Resetting state

sboot keeps two small files in your OS config dir (sboot where prints the state path; SBOOT_STATE_DIR relocates both):

• state.json — how deep you are in each check's hints, your last local verdicts, and a cached copy of your progress for offline orientation. Deleting it is always safe: your progress and completions live on the server, and your code lives in your repo.
• credentials.json — the token sboot login stored, mode 0600. Deleting it is sboot logout. Reconnect with sboot login.

Likewise the cache (SBOOT_CACHE_DIR): delete it and the next sboot test re-fetches the tests and grader.

If you suspect a token has leaked, rotate on /account — that revokes every token on the account, including every machine connected with sboot login, and mints one fresh. Reconnect the machines you still want.

Pinning or rolling back the CLI

The installer can install any released version, not just the latest:

SBOOT_VERSION=sboot-v0.3.0 curl -fsSL https://sourceboot.com/install.sh | sh

(0.3.0, v0.3.0 and sboot-v0.3.0 all work.) Every release stays downloadable — releases are never deleted or re-tagged, so a pinned version keeps installing. The releases page lists them all, each with its pin command in the notes. If a release is ever bad, its notes say so and name the version to use.