Troubleshooting

This guide lists common errors and how to resolve them.

Git repository not found

Symptom

Error: not a git repository

Cause

kanbus init requires a git repository to exist in the current directory.

Fix

Initialize git, then retry:

git init
kanbus init

Malformed JSON in an issue file

Symptom

Error: failed to parse issue file

Cause

An issue JSON file under project/issues/ is not valid JSON or does not match the required schema.

Fix

• Open the referenced file in project/issues/ and validate the JSON.
• Ensure required fields are present and match the schema in VISION.md.
• If the file is not recoverable, restore it from git history.

Invalid workflow transition

Symptom

Error: invalid transition from 'open' to 'blocked' for type 'task'

Cause

The transition is not permitted by the workflow defined in .kanbus.yml.

Fix

• Check the workflow rules in .kanbus.yml.
• Use a valid intermediate status, or adjust the workflow definition.

Corrupted or stale cache

Symptom

• Issue list is missing items
• Queries show outdated results
• Cache file cannot be parsed

Cause

The cache in project/.cache/index.json is stale or corrupted.

Fix

Delete the cache file; it will be rebuilt on the next command:

rm -f project/.cache/index.json

Daemon connection issues

Symptom

• Error: daemon connection failed
• Error: daemon disabled

Cause

The daemon socket is stale or daemon mode is disabled.

Fix

• Stop and restart the daemon:

kanbus daemon-stop
kanbus daemon-status

• To bypass the daemon for a single command:

KANBUS_NO_DAEMON=1 kanbus list

Console serves stale UI or favicon/module-script errors

Symptom

• Browser shows module MIME errors after reload (HTML returned for JS).
• GET /favicon.ico returns 500.
• Behavior changes between runs because different kbsc processes answer on different ports.

Cause

• An older kbsc process is still listening on the expected port.
• Your global kbsc install (~/.cargo/bin/kbsc) is older than the workspace build.

Fix

• Check active listeners/processes:

pgrep -x kbsc
lsof -nP -iTCP -sTCP:LISTEN | grep kbsc

• Stop stale processes and restart:

pkill -x kbsc

• Use the workspace binary while developing, or refresh the global install:

rust/target/debug/kbsc
# or
cargo install kanbus --bin kbsc --force

Workflow or hierarchy validation failures

Symptom

Error: hierarchy violation

Cause

A parent-child relationship violates the configured hierarchy or a non-hierarchical type has children.

Fix

• Review the hierarchy and types settings in .kanbus.yml.
• Update the issue to a valid parent or change the issue type.

OPENAI_API_KEY is not set

Symptom

OPENAI_API_KEY is not set. Run 'kbs setup ai' (or 'kanbus setup ai') to store it once in
~/.kanbus.env, or set it in your shell environment or the project .env file.

Cause

Compaction, right-now summaries, standup rollups, and wiki summarization call an LLM, and no OPENAI_API_KEY (or provider-equivalent variable) was found in the shell environment, ~/.kanbus.env, or the project .env.

Fix

Store a key once for your user:

kbs setup ai
# or: kanbus setup ai

Or set OPENAI_API_KEY in your shell environment or the project .env file. Check kbs setup ai --status or kbs doctor to confirm which source provides the key.

Still stuck

If you cannot resolve an issue, run kanbus validate to get a full integrity report and inspect the errors for additional context.