Troubleshooting
Start with the reported check and diagnostic, then repair the input or environment that prevented analysis.
Capture the diagnostic before changing policy
Swarm requires Node.js 22.13.0 or newer. Run these commands from inside the intended Git repository. doctor diagnoses setup without running a scan; it can make a bounded OSV connectivity probe when applicable.
Read the affected check, error code, repository-relative path, snapshot side, and remediation in the complete result. A diagnostic about the baseline is not fixed merely by editing the target configuration.
doctor inspects working-copy configuration. checks inspects staged configuration. If they disagree after an edit, inspect what was staged before assuming either command ignored your settings.
node --version
npm ls zedbee --depth=0
npx zedbee doctor --format json
npx zedbee checks --format jsonFind the right next check
| Symptom | Likely explanation | Next step |
|---|---|---|
| Scan reports no changed files | The index matches HEAD, or the intended edit was never staged. | Inspect git diff --cached. In clean CI, use an explicit committed base comparison. |
| New settings appear to be ignored | The file is saved but not staged, or CI checked out a commit without the update. | Stage locally; commit and push for base-mode CI. |
| Hook cannot find Zedbee | The local development dependency is missing or was omitted during installation. | Restore dependencies from the repository’s lockfile, including dev dependencies. |
| Typed lint cannot load a project | A selected TypeScript file is outside the loaded projects in one snapshot. | Check both baseline and target project coverage; do not silently drop typed rules. |
| OSV check is incomplete | Connectivity is unavailable, or dependency input/response validation failed. | Read the error classification before choosing an outage exception. |
| Only some findings are visible | Automatic output or forced Ink is a bounded preview. | Read the complete report or request explicit text, JSON, or SARIF. |
| Fix skipped a file or only applied some changes | A conflict, stale preview, unsupported fix, or file-operation issue was reported. | Review changed and skipped files before retrying. |
Avoid disabling a check just to remove an unexpected diagnostic. Use exclusions or weaker policies only when you deliberately accept the coverage change and document why.
Verify the exact content Swarm is comparing
An unstaged edit is not part of an ordinary scan. Review the working diff and stage the specific files you want checked. An intent-to-add entry has no staged content and is excluded as unstaged.
In base mode, Swarm reads committed HEAD, not files modified after checkout. The comparison ref and sufficient common history must already be local. If ancestry is missing, fetch the intended ref and enough history before retrying; Swarm does not fetch automatically.
Configuration follows the target: staged locally, committed HEAD in base mode. You do not need to merge settings into main first. --base origin/main selects the code comparison, not the settings branch.
git status --short
git diff --cached --stat
git diff --cached -- .zedbeerc.jsonc
git rev-parse --is-shallow-repository
git show-ref --verify refs/remotes/origin/main
git merge-base --all origin/main HEADRestore the dependency instead of bypassing the hook
Generated hooks intentionally use npx --no-install zedbee scan. They will not download a missing scanner while a commit is in progress. If the dependency is already recorded in your package manifest and lockfile, restore it with your package manager, including development dependencies.
The example is for npm repositories. npm ci replaces the installed dependency tree and can run package lifecycle scripts; use the repository’s normal installation procedure and trust requirements. Use the matching package manager for pnpm, Yarn, or Bun projects.
If hook wiring also needs attention, init --format json previews the detected integration without applying it. Review the proposal before approving an update. Repeated initialization should not duplicate an existing Zedbee invocation.
npm ci --include=dev
npm ls zedbee --depth=0
npx zedbee init --format jsonRepair unsupported or incomplete inputs deliberately
| Diagnostic area | What to inspect | Resolution |
|---|---|---|
| Typed lint | Every selected TypeScript file must belong to a loaded project in each snapshot, including unchanged workspace source used by typed lint. | Repair project coverage. For intentionally untyped paths, a narrow override can use typeInformation: when-available, accepting the loss of typed rules. |
| Native analyzer configuration | Swarm does not load project ESLint, Prettier, or custom plugin configuration. | Express supported settings in .zedbeerc.jsonc and inspect them with checks. |
| Git LFS, submodules, binary input | Pointers do not provide the underlying source; selected binary input can be incomplete for enabled text/source checks. | Read all affected paths. Use check-specific pathExclusions only for intentionally unsupported coverage. |
| Secret detection | Invalid UTF-8, oversized input, symlinks, or unavailable selected content can prevent analysis. | Follow the path-specific remediation. Secret scanning does not cover complete Git history. |
| Vulnerability lockfiles | Unsupported formats, size limits, malformed content, or pnpm/modern Yarn YAML aliases. | Regenerate with the package manager. Use text bun.lock rather than legacy bun.lockb; do not hand-author alias-based reuse. |
| Managed Knip resolution | An imported package committed beneath node_modules can enter snapshot-controlled module resolution. | Remove the committed package from the project’s tracked inputs and restore dependencies through its package manager and lockfile. |
| Large or framework-heavy workspaces | Large jscpd argument lists or unsupported managed Knip configurations can fail analysis. | Retain the diagnostic and reproduce the limitation; do not interpret an incomplete check as no findings. |
An OSV availability failure is different from invalid lockfile data or a rejected response. onUnavailable: "warn" only handles supported outage cases. It does not repair malformed input or supply an offline advisory database.
Treat retained reports and working changes separately
If the terminal preview is abbreviated, open the complete report path or request an explicit export. Temporary reports are not archives: after their configured age they are eligible for cleanup, and the OS may remove them sooner.
REPORT UNAVAILABLE means report delivery failed. Swarm restores every finding to terminal output and does not print a false report path. Inspect permissions, available storage, and maintenance warnings; retain an explicit export when you need a durable copy.
Snapshot cleanup failure is different: it makes the scan incomplete. Inspect and remove only a confirmed stale Zedbee snapshot directory, using a validated reported path when available. Correct filesystem permissions or locks before another scan; repeated failures can leave additional snapshots.
For managed fixes, review git diff and the skipped-file reasons before staging. Exact edits can be rejected where they overlap unstaged work; selected formatting can affect the whole working file. If a write’s durability could not be confirmed, inspect the file rather than automatically retrying the same operation.
npx zedbee scan --format json --no-source > zedbee-report.json