Troubleshoot authoring

This page is for an author: writing knowledge components, or building and publishing a case. If no /fito- command is offered at all, start at Troubleshoot installation.

Authoring stops are usually deliberate. The commands refuse rather than guess, and most refusals name the fix. This page groups the ones that come up across several commands.

Before you begin

Two things are true of a working authoring session, and a great many symptoms here are one of them being false:

• The technology and the major line you are naming already exist in Fito.
• You are logged in, for the three commands that write — /fito-create-or-update-technology, /fito-push-knowledge and /fito-publish-case.

The vocabulary does not hold what you need

The same underlying gap surfaces in four commands with four different messages.

Where	What you see	What it means
/fito-identify-	The Fito vocabulary holds no <slug> technology…	The slug is absent
/fito-push-knowledge	No technology found for "<slug>".	The slug is absent
/fito-push-knowledge	"<name>" (<file>) was not stored: technology "<slug>" has no version "<v>"	The technology exists; the major line does not
/fito-case-design	“The Fito vocabulary doesn’t hold these declared technologies yet”	A slug is absent, or the major line you named is
/fito-case-design	“These components don’t exist in the Knowledge Repository yet”	Nobody has written up the knowledge the case needs

A misspelt slug is not a reason to provision

Provisioning the misspelling creates a second, independent technology beside the real one, and components pushed against the two land on different rows. Check the spelling before you reach for Provision a technology.

Two more things this message does not mean:

• A server that is down is not a missing technology. When a lookup fails for any reason other than not-found, the command reports that failure as it arrived and stops, without the provision-it-first advice.
• Do not shrink a case to fit what exists. Dropping a component the case genuinely needs makes a worse case. The vocabulary is what should grow.

One check before you run the whole pipeline: if every candidate under one technology came back missing, suspect the major line rather than the vocabulary.

A near-duplicate stops the run

Writing a technology or a component compares it with what Fito already holds. A match stops the run with nothing written, and lists every match with the layer that found it — dedup-key for a deterministic collision, trigram for a fuzzy one.

Near-duplicate technologies found (409): <message>

  <slug> — "<name>" (<layer>)

The choice is yours, and the command never makes it for you:

Choice	When	What happens
Reuse	The match is your thing	Re-run declaring the matched slug. The run becomes an update. The preferred answer
Re-declare	The match only resembles yours	Re-run with a different slug
Override	The match is a false alarm	A new, independent row is created beside every match

An override is not a shortcut past a real duplicate: components pushed against two slugs land on two different technologies and never meet. The full account is on Provision a technology.

Nothing was ingested

No source found at <docs-path>. means the pipeline had nothing to read.

1. Prefer the case’s own source tree: pass --source <path>.
2. Otherwise fetch documentation first — --fetch with --urls <file>, or /fito-fetch-urls-content on its own.
3. Or point --docs at a folder an earlier fetch already filled.

The two ingestion sources are not equals, and which to reach for is on Ingest a source tree.

A generated component will not push

Never edit a component file to make it pass. The generated files are read-only inputs to the push. When one is wrong, regenerate it and push the new file.

A failed file is recorded and the push moves on. One bad file never stops the run. The message table is on Generate and push components.

The structural validator fails

The validator reports every violation at once, each scoped to the .case/ file that produced it and usually to a field path inside it.

Read the path as well as the message. On its own a message can read Invalid input: expected string, received undefined, which names no field.

Fix the named files and run it again. Do not regenerate the tree over an error you can fix. Field by field, the contract is on The .case/ file contract; reading the output is on Validate the .case/ folder.

A publish stops

Every one of these is safe to re-run. The repository is never duplicated, and a registered draft is reused rather than re-minted.

What you see	What to do
“The working tree has uncommitted changes”	Commit or stash, then re-run
“The local solution branch … does not exist”	Build the exemplar branch, then re-run
“Your local gh account … is not your Fito account’s linked GitHub identity”	Re-run with --accept-gh-mismatch if that is intended. The confirmation is yours to give
“… is already a published Fito case”	This is an update, not a first publish
“The .case/ tree fails structural validation”	Fix the named files and re-run
A rejection from the server with an HTTP status	Usually an unresolvable reference, or a failed reachability ping

A failed reachability ping means the refs did not land. The server checks the version tag and the solution branch itself, so check both on GitHub before re-running. Both tables in full are on Publish a case.

A new version will not publish

Publishing a second version has stops of its own, and the one that surprises authors is the frozen reference set:

What you see	What it means
“The knowledge-reference set is frozen across versions, and this tree changes it”	This edit belongs on the other route — a successor case, not a new version
“.case/manifest.yaml is stale for the new version”	submission.target_branch still names the old version
“.case/solution.yaml is stale for the new version”	branch: still names the old version
“manifest.version is still …”	The version did not move, or moved backwards

The frozen-reference stop itemises exactly what was added and what was removed. Read that list before deciding — it is the difference between a typo and a real change of scope. See Correct or retire a published case.

Still stuck

Collect these before asking for help:

• The exact command, with every flag.
• The first error line, verbatim, including any HTTP status.
• The technology slug and the major line you named.
• Whether you are logged in, and whether the working tree is clean.

What’s next

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