Troubleshoot a blocked step

These checks apply to the current stable Bee release. Compare the exact command, installed version and returned error code. Preserve your profile and existing data; a failed example is not a reason to reset them.

Symptom	Check and next action
bee is missing or the wrong version runs	command -v bee on macOS/Linux, Get-Command bee -All in PowerShell; compare dotnet tool list --global, --local or --tool-path ./bee-tools with your installation scope. Invoke that exact executable.
--version or version is rejected	Run bee --version (or bee -v) for the installed version; bee --version --json adds build and platform details. bee version is not a command. If the flag is rejected, check which executable your shell resolves and the installation scope.
NuGet package not found	Check the exact version, feed and .NET 10 SDK with dotnet --info. Follow install/update; a newly published package may still be indexing.
update check exits 5	The check is unavailable, not evidence that you are current. Read checkStatus and retry when the feed is reachable. Do not reinstall your profile.
bee is not initialized	For memory, rules and plans follow shared setup. For a local first result use token estimate; it does not need init.
Shared connection fails	Check the selected BEE_HOME, bee config path, database host/port and reachability. Use the same profile as the working terminal. Do not log connection strings.
Saved memory/plan is missing	In the intended checkout run bee remember stats --json. Compare actual scope and database; linked worktrees may resolve differently. Do not create another record until you locate the right scope.
Graph missing/stale	bee graph status --check --json: 3 means missing, 6 stale. Run bee graph build --json, inspect coverage, then query again. Outline uses its own exit contract.
Analysis has no findings but exits 5	Inspect coverage, unsupported context and missing compiler/reference information. Follow engine requirements and run your actual project checks. Partial is not clean.
lint --rules is empty or lint --detect finds no tool	Neither runs lint. --rules reads guidance; --detect previews the tool. Configure/run the project’s actual linter; an empty rule set is not a passed check.
Local text/report path is refused	Select a regular UTF-8 file under an absolute physical root. Avoid symlinks; use pwd -P on macOS/Linux. Check command limits and error codes rather than copying private files elsewhere blindly.
A summary/assessment exits nonzero	A TRX exit 1 can correctly report a failed test. qa assess is diagnostic and exits 5; qa run executes the declared checks and returns 0 only for verified declared criteria, 1 for repair required, 4 for invalid input and 5 for missing/incomplete evidence. Read the report status and evidence workflow before treating a parser exit as the original runner result.
Skill lookup is unconfigured or empty	Distinguish connection errors from no matches; follow Skills and how-tos. Never guess a catalog ID.
Plan mutation conflicts	Read bee plan show <plan-id> --json; compare revision, actor, generation and lease. Reclaim only after resolving ownership. Preserve request ID/payload for outcome_unknown. See Plans.
Peer exists but does not answer	Inspect message status and your own inbox; check native-session support and receiver health in Collaboration. Presence or transport acceptance does not prove the model read the message.
Rule absent from context	Check scope, enabled/archive state, file glob and hook installation, then inspect steering.
guide task lists commands but work is not complete	The guide is advisory and reads supplied labels, not source or readiness. Run its selected checks and inspect raw results; see command reference.
qa run cannot execute a check	Inspect errorCode, check argv and declared inputs, and use an absolute interpreter or reviewed wrapper. It does not forward ambient PATH; checks may write files. See QA execution.
Data appears under the wrong Bee instance	Check bee instance which . --json and bee --version in the exact checkout. Session pins and explicit instance selection can override directory discovery; a conflict exits 8. See instance isolation.

Prepare a useful issue report

Include OS/architecture, installation scope, Bee version, exact command with secrets removed, working-directory role, actual exit and minimal synthetic input. Include expected versus observed behavior and the smallest relevant JSON fields. Exclude credentials, private prompt contents and unrelated logs. If the example itself fails, link the guide page and identify its step.

Return to First run or Command reference.