Troubleshoot installation

Everything on this page happens before you have done any work in Fito: the session will not start, the commands are not there, a package is too old, or the login will not finish. Problems that appear while you are working a case or authoring content are on their own pages, linked at the end.

Before you begin

A healthy install looks like this, and each part has its own section on this page:

• Exactly one Fito install, from npm. pi list shows npm:fito-tui, and no clone of the Fito repository.
• pi-subagents 0.68.0 or newer, for the eleven commands that use a worker persona.
• A Fito package the Fito server still accepts.

No /fito- command is offered

Type /fito- in the session. If the completion list offers nothing, Fito is not loaded.

1. Leave the session.

2. Check that the install recorded:

   pi list

   If the list does not show npm:fito-tui, install Fito, as in Install and prerequisites.

3. If the list shows it, run pi config and turn Fito’s resources on again. pi config turns a package off without removing it.

4. Start pi again and type /fito- a second time.

Confirm it worked: the list offers /fito-login.

pi refuses to start: Tool "fito_knowledge_fetch" conflicts with …

The session does not start at all, and the error names two absolute paths and no remedy.

pi loads Fito twice. The usual cause is a clone install of Fito beside the npm install, because earlier versions of the install page installed Fito from a clone. pi treats a duplicate tool registration as a fatal extension-load error, and raises it before it checks your credentials. The session dies rather than starting degraded.

One of the two paths in the error is in your clone of the Fito repository. That is the install to remove. The steps are in Move off a clone install.

Unknown tool: subagent, or /run is not recognised

pi-subagents is not installed. Eleven Fito commands hand their work to a worker persona and reach it through that package — the tutor and the rubric scoring among them.

pi install npm:pi-subagents

Then restart pi.

The same cause has a quieter symptom: Fito’s worker personas are declared for pi-subagents in the package manifest, so without that package nothing loads them. The session says so at startup.

Fito needs pi-subagents 0.68.0 or newer

Your pi-subagents is older than the version Fito’s worker personas need. Fito checks it as pi starts, and shows:

Fito needs pi-subagents 0.68.0 or newer. Run: `pi update --extensions`

To update it, run this in your shell, then start pi again:

pi update --extensions

Confirm it worked: the message does not appear when pi starts.

Your Fito TUI … is too old

The Fito server accepts a Fito package only from a minimum version up. Fito asks the server as pi starts, and the server also refuses each command that an older package sends. The message names your version and the server’s minimum, for example:

Your Fito TUI 0.2.1 is too old. The minimum is 0.3.0. Update it with: `pi update --extensions`

To update, run this in your shell, then start pi again:

pi update --extensions

If the message comes back, Fito is probably a clone install, which pi update skips. Move off it, as in Move off a clone install.

The login page opens on the wrong Fito

/fito-login opens a browser at the address in FITO_URL. When that variable is unset, it opens the hosted Fito, at https://fito.codes. So the login page opens on the wrong Fito when FITO_URL names another Fito, or when it is unset and you meant a local one.

Check it in the shell you start pi from:

echo "$FITO_URL"

Set it to the Fito you mean, or unset it for the hosted Fito, then start pi again. The full list is on TUI configuration.

The login never completes

/fito-login waits five minutes for the browser to hand the tokens back, then gives up. Nothing is broken by a timeout — run it again.

What you see	What to do
The browser does not open	The terminal prints the URL. Open it yourself
You signed in, and the terminal is still waiting	Return to the tab; it tells you when the handoff is done
It timed out	Run /fito-login again

Confirm a login worked:

✓ Logged in. Credentials saved to ~/.fito/credentials (mode 0600).

If a later command still asks you to log in, the credentials file may be half-written — a malformed file is read as not logged in rather than as an error. Run /fito-login again to rewrite it.

Still stuck

Collect these before asking for help. Together they identify every cause on this page:

• The output of pi list.
• The folder you started the pi session in.
• The exact first error line, including any paths it names.
• Whether FITO_URL is set, and to what.

What’s next

• Troubleshoot casework — opening, the tutor, evaluating and submitting.
• Troubleshoot authoring — the knowledge pipeline and case authoring.