Troubleshoot casework

This page is for a learner whose session is working and whose commands exist, but whose case will not. If no /fito- command is offered at all, start at Troubleshoot installation.

Each symptom below names the cause and points at the page that carries the full account.

Before you begin

Four things are true of a working case, and most symptoms here are one of them being false:

• You are logged in to Fito from the terminal.
• gh is installed and authenticated as the account linked to your Fito profile.
• The case is open at ~/.fito/cases/<case-id>/.
• Your work is committed on the case’s working branch.

A case will not open

What you see	What it means	What to do
A “case source malformed” report, and no branch	The case’s own .case/ does not validate. Nothing is wrong on your side	Try again later, or report the case
A refusal naming a deprecated case	The case has been withdrawn	Pick another. Do not work around it
⚠ This case has been deprecated…, then a normal open	The case is on its way out but still workable	Carry on
It will not overwrite a non-empty checkout	You already have this case open	Work in ~/.fito/cases/<case-id>/
GitHub CLI is not ready — install gh and run 'gh auth login'.	gh is missing or signed out	Install it, then gh auth login

The full account is on Open and work a case.

The tutor will not answer

What you see	What it means
It points you at /fito-case-open and stops	No case is open. The tutor reads your checkout, and there is nothing to read
Unknown tool: subagent	pi-subagents is missing — see Troubleshoot installation
A refusal	You asked for the exemplar solution, the quiz answer key or the rubric’s scoring key

A refusal is structural, not a mood

The tutor persona holds no filesystem tool. It reads documents by an enumerated key, and the solution, the rubric and the quiz have no key in that set. There is no phrasing that reaches them, so asking harder is not worth your time. Ask a narrower question instead — Ask the tutor lists the ones that work.

An evaluation will not run

/fito-evaluate runs entirely on your disk. It needs no login, so a login is never the cause.

What you see	What it means	What to do
It cannot find the case	The checkout at ~/.fito/cases/<case-id>/ is gone	Re-open the case
Unknown tool: subagent	The rubric’s ai and hybrid criteria are judged by a worker persona	Install pi-subagents
A criterion scores 0 with captured output	An automated criterion’s command failed	Read the output — it is shown for that reason

A preview records nothing. Running it again costs you nothing either. See How a case is scored.

A submission is refused

/fito-submit checks your identity before it pushes anything, so a refusal here means nothing reached GitHub.

What you see	What it means	What to do
Your Fito account has no linked GitHub identity…	Nothing is linked	Sign in to the web app and choose Continue with GitHub
GitHub account mismatch: your Fito-linked account is @… but gh is authenticated as @…	Two accounts, and Fito will not guess	Move either side to match the other
GitHub CLI is not ready — install gh and run 'gh auth login'.	gh itself is not ready	This is an install problem, not an account one
The push was rejected: your fork's '<branch>' branch has diverged…	Your fork already carries a previous attempt	Do not force-push. Re-open the case and choose Resume or Start over

The two identity refusals and the reason the check runs first are on Submit and read your result.

Never force-push a case branch

A force-push destroys the previous attempt’s history, which is the evidence the submission rests on. Re-opening the case gives you the same choice safely, as two named options: Resume keeps the branch and the open pull request; Start over deletes the fork’s branch, which closes that pull request. Both are described on Open and work a case.

Nothing appears on your profile

A submission is recorded after the pull request is opened and the rubric is scored, not at the moment you run the command.

What you see	What it means
The command finished but the profile is unchanged	Re-run /fito-submit. It is safe: it picks up the existing pull request and retries the record
Your attempts are missing from the case page	You are signed out in the browser. /cases/<id> shows attempts only to a signed-in reader
A competence did not move	A recorded standing never moves down, and a lower result leaves it where it was

Where results land is on Submit and read your result and Your learning analytics.

Still stuck

Collect these before asking for help:

• The exact command you ran, with the case id.
• The first error line, verbatim.
• Whether ~/.fito/cases/<case-id>/ exists, and whether your work is committed there.
• The output of gh auth status.

What’s next

• Troubleshoot installation — when the session or the commands are the problem.
• Troubleshoot authoring — when you are writing content rather than working a case.