Troubleshooting

Troubleshooting

Real errors people hit, and what they actually mean. If your problem is not here, ask in Q&A — and the answer gets added to this page.

---

kq: error: unrecognized arguments: export ...

You are on an old kube-q. This was a real defect until 2026-08-08 (PyPI served 1.4.3, which predates the subcommand interface). It is fixed:

pip install --upgrade kube-q
kq --version        # must say 1.5.0 or newer

Anything below 1.5.0 is the cause. Applies to export, postmortem, replay, findings, digest, detector, preference, completion, help.

Do not use the old git+https://… workaround that this page and the install guide used to recommend — it pins you to a commit instead of a release.

Trap: kq <subcommand> --help exits 0 even on a build that lacks the subcommand, because argparse's -h fires before it validates the unrecognized positional. Reproduce without --help.

pip install kubeintellect gives an old version

Upgrade — the current release is 2.2.0 and it is on PyPI:

pip install --upgrade kubeintellect

Container images carry the same version: ghcr.io/mskazemi/kubeintellect:2.2.0.

The published package says the licence is MIT, but the repo says AGPL

The code is AGPL-3.0-or-later (with a commercial option — see LICENSING.md).

Fixed on PyPI as of the 2026-08-08 release. kube-q 1.5.0 and kubeintellect 2.2.0 both report GNU Affero General Public License v3 or later (AGPLv3+). If you are reading MIT, you are looking at a pre-relicense version — upgrade.

Two related metadata defects are still open, both good first issue:

• #56 — the Homebrew formula still says MIT and pins a version that never existed.
• #74 — kube-q's PyPI page links to the wrong repository, and ki-protocol's page has no licence classifier at all.

---

Contributing

make lint fails on a clean checkout

Expected. make lint runs ruff format --check, which is not a CI gate and would reformat ~108 files. It is known debt, tracked on the ROADMAP.

Run the real gates instead — make setup from the repo root, or from v4/:

uv run ruff check packages/kubeintellect-server/app/ packages/ki-protocol/
uv run mypy packages/kubeintellect-server/app packages/ki-protocol packages/kube-q/kube_q
uv run python -m pytest tests/ -q
cd packages/kube-q && uv run python -m pytest tests/ -q

My PR has no CI checks and the merge box is blocked

Expected on your first PR, and not your fault. GitHub runs no workflows on a fork PR from a first-time contributor until a maintainer clicks "Approve and run workflows". Nothing is wrong with your branch and you don't need to do anything.

ruff wants to be upgraded past 0.16

Don't. The <0.16 pin is deliberate — 0.16's default rules report 438 findings that need their own cleanup pass. Tracked in #64, and Dependabot is configured to ignore it.

mypy suddenly reports errors

The workspace sits at zero errors across 171 files and Types (mypy) is a required check. If it complains, it is from your change.

One special case: do not "fix" an injected RunnableConfig annotation. It must stay

config: Annotated[RunnableConfig, InjectedToolArg] = None,  # type: ignore[assignment]

because langchain_core matches that parameter by identity. Widening it to RunnableConfig | None stops the run config being injected, which silently disables RBAC and the HITL gate. Full analysis in #54 (closed — the code is already correct at all three sites; the fix that issue originally prescribed is the harmful one). The rule is enforced going forward via #75 and AGENTS.md safety invariant #6.

Tests pass locally but I changed a command's output

If your change adds or edits a command that emits a diagnosis, report, postmortem, or summary, run it by hand against a resource that does not exist (a made-up session id, no cluster configured). It must refuse with a non-zero exit code, not return a plausible-looking result.

This is the one failure mode the project cannot ship, and the test suite cannot catch it — a merged PR once returned a hardcoded status: ok with an invented high-severity finding on a machine with no cluster, and all its tests passed because they asserted the constant against itself.

---

Running it

It refuses to scale/delete something

Working as designed. Every mutating action stops for explicit human approval, gated by RBAC (admin / operator / readonly). See The Safety Model.

If you are on a readonly API key, you get [Permission Denied] — that is the role layer, not a bug.

Which LLM providers work?

OpenAI and Azure OpenAI are the supported, tested paths. OPENAI_BASE_URL already works for OpenAI-compatible endpoints (Ollama and friends), but making that a first-class, documented, tested path is open work — #17, and it is one of the most-requested items.

Where do logs / traces go?

Prometheus, Grafana, Loki and Langfuse are installed by the shared infra targets (make monitoring-install, make langfuse-provision). See Architecture Overview.

---

Still stuck?

• 💬 Q&A discussion — best for "how do I…"
• 🐛 Open an issue — for something broken
• 🔒 Report privately — for anything security-related

SUPPORT.md says what to include so the first reply can be useful.