Docs
/
Guide

Troubleshooting

Recovery procedures for setup problems and broken Kibi state.

Upgrading and branch recovery

Kibi is in beta. Package upgrades do not require deleting the knowledge base. kibi migrate previews a structured plan and applies approved schema and storage updates. kibi status reports when the current branch is waiting on that plan.

  1. Check the branch:

    bash
    kibi status

  2. Preview the migration:

    bash
    kibi migrate --dry-run

  3. Apply it. --yes applies the plan without a prompt. --apply-safe applies only approved deterministic actions and requires the plan hash from the preview. See kibi migrate.

    bash
    kibi migrate --yes

Migration upgrades entity schemas and the on-disk layout, including a leftover documentation/ tree or .kb/config.json. It keeps authored knowledge. It does not wipe .kb/. When a predicate fact is in the wrong namespace or still uses an old argument spelling, the same plan can move it to the only matching schema and rewrite that spelling to the declared constant. Review the plan hash before applying. Repairs that need a judgment stay as review items.

If the compiled store for this branch is incomplete or unreadable, preview a rebuild before applying it. Recovery recompiles that store from authored sources and moves the previous bytes under .kb/recovery/. See kibi branch.

bash
kibi branch recover
kibi branch recover --apply

kibi sync recompiles the branch store from the authored Markdown and manifests. Use it after you have fixed those sources. It is not the upgrade command, and deleting .kb/branches is not the upgrade path.

Stale or Dirty Symbol Coordinates

If kibi check --staged or the pre-commit hook fails with errors about unstaged symbol changes:

Symptom:

  • Commit blocked due to modified code symbols not being reflected in the manifest.
  • Error message indicates .kb/symbol-coordinates.yaml is out of sync.

Resolution:

  1. Refresh the coordinates:

    bash
    kibi sync --refresh-symbol-coordinates

    This command rescans your source code and updates the line/character coordinates in .kb/symbol-coordinates.yaml.

  2. Stage the changes:

    bash
    git add .kb/symbol-coordinates.yaml

  3. Retry the commit.

Dangling References

If kibi check fails with no-dangling-refs violations:

Symptom:

  • Check reports that entities reference IDs that don't exist
  • Relationships point to deleted or missing entities

Resolution:

  1. Identify the dangling references:

    bash
    kibi check

    Note the specific entity IDs and relationship types reported.

  2. Fix the source files:

    • Update Markdown frontmatter to use correct entity IDs
    • Verify that all linked entities actually exist
    • Remove relationships to deleted entities

  3. Re-sync:

    bash
    kibi sync

  4. Re-check:

    bash
    kibi check

Git Hook Issues

Hooks Not Installing

If kibi doctor reports missing git hooks:

  1. Reinstall hooks:

    bash
    kibi init

    This reinstalls the hooks (pre-commit, post-checkout, post-merge, post-rewrite) by default.

  2. Verify hooks are executable:

    bash
    ls -la .git/hooks/

    The hooks should be executable files (not just .sample files).

  3. Manually check hook permissions:

    bash
    chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/post-checkout
chmod +x .git/hooks/post-merge
chmod +x .git/hooks/post-rewrite

Hooks Not Running

If git operations don't trigger kibi hooks:

  1. Check hook files exist:

    bash
    ls -la .git/hooks/ | grep -E "pre-commit|post-checkout|post-merge|post-rewrite"

  2. Check hook content:

    bash
    cat .git/hooks/pre-commit

    Should resolve the kibi binary into KIBI_BIN and then invoke it (e.g. "$KIBI_BIN" check --staged).

kibi: not found Inside Git Hooks

Git runs hooks with your shell's PATH, which does not include node_modules/.bin. Kibi-managed hooks handle this by resolving the binary themselves: they check PATH first (global installs) and then walk up from the repository root looking for node_modules/.bin/kibi (project-local installs, including monorepo workspace roots).

If you still see kibi: not found (or cannot locate the kibi CLI) from a hook:

  1. Confirm how kibi is installed:

    bash
    command -v kibi
ls node_modules/.bin/kibi

    At least one of these must exist. If neither does, install kibi globally or add it as a project dependency.

  2. Regenerate the hooks with the current template:

    bash
    kibi init

    Hooks generated by older kibi releases invoked bare kibi and fail for project-local installs; re-running kibi init replaces only the Kibi-managed section with the self-resolving template.

  3. Reinstall hooks:

    bash
    kibi init

    Re-running kibi init also refreshes .gitignore entries for .kb/.

Hook Conflicts

If you have existing git hooks that conflict with kibi:

Warning: Re-running kibi init overwrites Kibi-managed hooks. Make sure to back up custom hook logic first.

  1. Backup existing hooks:

    bash
    cp .git/hooks/pre-commit .git/hooks/pre-commit.backup
cp .git/hooks/post-checkout .git/hooks/post-checkout.backup
cp .git/hooks/post-merge .git/hooks/post-merge.backup
cp .git/hooks/post-rewrite .git/hooks/post-rewrite.backup

  2. Install kibi hooks:

    bash
    kibi init

  3. Manually merge (if needed): Edit the hook files to combine both your existing hooks and kibi hooks.

KB Corruption

If kibi sync or kibi query produce errors:

  1. Check the environment:

    bash
    kibi doctor

    It confirms SWI-Prolog 9.0+, the .kb/manifest.json shape, and any leftover .kb/config.json that kibi migrate --yes should retire.

  2. Clear stale engines and locks. A crashed engine or a removed worktree can leave a daemon or branch-store lock behind. Preview first, then apply:

    bash
    kibi engine janitor
kibi engine janitor --apply

  3. Recover the branch store. Recovery recompiles the store from authored sources and keeps the previous bytes under .kb/recovery/:

    bash
    kibi branch recover
kibi branch recover --apply

Configuration Issues

Kibi does not accept user-configured entity paths or persistent check disabling. Knowledge lives under canonical .kb/ lanes (requirements/, scenarios/, tests/, facts/, adr/, flags/, events/, plus symbols.yaml).

If kibi sync doesn't find your documents:

  1. Confirm they are under .kb/<lane>/, not a relocated documentation/ tree. Legacy documentation/ knowledge is migrated with kibi migrate --yes.
  2. Executable e2e harnesses stay outside the knowledge lanes (for example documentation/tests/e2e/). Only TEST-*.md belongs in .kb/tests/.
  3. --rules on kibi check is an invocation-time diagnostic filter only; it does not persist.

Environment Diagnostics

Run comprehensive diagnostics:

bash
kibi doctor

This checks:

  • SWI-Prolog installation
  • .kb/ directory existence
  • .kb/manifest.json validity
  • leftover .kb/config.json that still needs migration
  • Git repository presence
  • Git hooks installation

Agent CLI JSON route failures

The dedicated CLI JSON routes are peer operation access for agents that do not have visible MCP tools.

  • Exit 2 means invocation or input validation failed. Confirm --input <file|-> is present, the JSON root is an object, and no business flag or positional argument is mixed with JSON mode.
  • Exit 1 means validated operation execution failed. Inspect Error [CODE]: detail on stderr, then check SWI-Prolog, branch freshness, filesystem permissions, or network availability as appropriate for that operation.
  • Exit 0 writes one structured JSON value to stdout. If an integration expects a table or prose, use the human flag mode instead of --input.

Use a project-local binary (npm exec -- kibi, pnpm exec kibi, or yarn exec kibi) so CLI and MCP resolve the same package versions.

OpenCode shows "workspace needs Kibi bootstrap" before the TUI

Symptom

When launching OpenCode in a workspace that already has a canonical .kb/ layout, you see a red error message saying "workspace needs Kibi bootstrap" before the TUI appears.

Root Cause

Health is determined by .kb/manifest.json plus the canonical knowledge lanes under .kb/. Relocated kibi-docs/* paths in leftover .kb/config.json are ignored. The false positive usually means the cached kibi-opencode plugin is older than the canonical-layout build, or the repo still needs kibi migrate --yes.

Inspection Commands

Check the cache plugin version:

bash
cat ~/.cache/opencode/node_modules/kibi-opencode/package.json

Recovery

Run kibi migrate --yes if knowledge still lives under documentation/ or leftover .kb/config.json is present. Then clear only the kibi-opencode plugin cache:

bash
rm -rf "$HOME/.cache/opencode/node_modules/kibi-opencode" "$HOME/.cache/opencode/bun.lock"

Then restart OpenCode.

Verification

After clearing the cache and restarting OpenCode, run from your workspace:

bash
timeout 20s opencode >/tmp/opencode-start.stdout 2>/tmp/opencode-start.stderr
grep -i "bootstrap" /tmp/opencode-start.stderr

If the grep returns nothing, the issue is resolved.

If the Problem Persists

If the false warning returns after clearing the cache, the published npm package may still contain the bug. Check for a newer version:

bash
npm view kibi-opencode versions

If you're on an old version, upgrade when a patch is available. Do not repeatedly clear the cache on the same broken version.

MCP startup resolves a stale kibi-mcp path

Symptom

MCP startup fails with a path resolution error pointing to an old kibi-mcp version, such as an older node_modules/.pnpm/kibi-mcp@<version> directory. This happens after upgrading kibi-mcp in a project that previously used pnpm or npx -y.

Root Cause

The MCP configuration or a package manager cache still references a stale path. npx -y, pnpm dlx/pnx, yarn dlx, and bunx without --no-install can mix local dependency resolution, registry fetches, and package-manager cache behavior in ways that produce ambiguous or outdated paths. Project-local execution avoids this by resolving only what is already installed in the project (npx --no-install / npm exec --no -- ... for npm, pnpm exec for pnpm, yarn exec for Yarn, or bunx --no-install for Bun).

These commands only control package resolution. They do not make parallel agents share or isolate an MCP process; the MCP client starts and owns the stdio server subprocess according to its own lifecycle.

Evidence-First Recovery

Do NOT delete all caches or node_modules as a first step. Capture evidence, inspect, and clean only what the evidence points to.

  1. Capture resolution evidence:

    bash
    npx kibi-mcp --print-resolution

    This prints the resolved binary path and version. If it points to a version older than what your package.json declares, the cache or config is stale.

  2. Inspect project lockfile and MCP config:

    bash
    grep "kibi-mcp" pnpm-lock.yaml
cat .vscode/mcp.json   # or opencode.json

    Confirm the lockfile lists the expected version and that the MCP config uses the local runner for your package manager, not an auto-install/hot-load command such as npx -y or pnpm dlx.

    For workspaces that intentionally run Kibi from a local checkout, also confirm the MCP config points at the checkout wrapper or binary directly. A command such as pnpm exec kibi-mcp resolves the application repository's installed node_modules package, not an external Kibi checkout.

  3. Targeted cleanup (only if evidence confirms a stale cache):

    bash
    rm -rf "$HOME/.cache/opencode/node_modules/kibi-opencode" "$HOME/.cache/opencode/bun.lock"

    Then restart your editor or OpenCode session.

Verification

After cleanup, rerun the evidence capture:

bash
npx kibi-mcp --print-resolution

The path should now match the version in pnpm-lock.yaml or package-lock.json.

Interpreting Sync Failures in OpenCode

When a background sync fails in OpenCode, the plugin logs an operational error with diagnostic metadata. To debug these failures, check the structured logs for the following fields:

  • syncStdout: The captured standard output from the kibi sync command.
  • syncStderr: The captured standard error from the kibi sync command. Often contains SWI-Prolog errors or file permission issues.
  • syncErrorMessage: The underlying system error message if the command failed to execute.

Idle Sync Suppression: To prevent terminal noise, the plugin suppresses background sync attempts triggered by session idle after a scheduler_sync_failed event is latched for the session. Syncs will still be attempted when you edit files or execute tools, which provides opportunities for recovery once the underlying issue is fixed.

To verify behavior or capture detailed logs, start OpenCode with stderr redirection:

bash
opencode 2> opencode-debug.log

Look for entries prefixed with [kibi-opencode] and check for the scheduler_sync_failed cause in the runtime overlay metadata.

Recovery Steps Summary

For installation issues, see the install guide.

Issue First Try If That Fails
Errors after an upgrade kibi migrate --dry-run, then kibi migrate --yes kibi branch recover --apply
Stale engine or lock kibi engine janitor kibi engine janitor --apply
Dangling references Update source files with correct IDs Verify and kibi sync
Hooks not working kibi doctor kibi init
Sync finds no docs Confirm knowledge lives under .kb/<lane>/ Run kibi migrate --yes if leftover documentation/ still holds knowledge
SWI-Prolog errors Check version Reinstall SWI-Prolog per install guide

For CLI command syntax and options, see CLI Reference