mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-25 08:48:08 +02:00
Move docs changes to specs repo
This commit is contained in:
Andrey Avtomonov
parent
2403f58eff
commit
573dfc20f0
8 changed files with 4 additions and 2793 deletions
|
|
@ -1,5 +1,5 @@
|
|||
{
|
||||
"title": "Getting Started",
|
||||
"defaultOpen": true,
|
||||
"pages": ["introduction", "quickstart", "troubleshooting-linux"]
|
||||
"pages": ["introduction", "quickstart"]
|
||||
}
|
||||
|
|
|
|||
|
|
@ -296,7 +296,7 @@ surface.
|
|||
| Anthropic health check fails | API key, model id, or access is invalid | Fix `ANTHROPIC_API_KEY` or rerun setup with a different key or model |
|
||||
| Vertex AI health check fails | Vertex API, Claude access, project, location, or IAM permissions are missing | Check the project, location, Application Default Credentials, and Vertex AI permissions |
|
||||
| OpenAI embeddings fail | `OPENAI_API_KEY` is missing or invalid | Export the key or choose local sentence-transformers embeddings |
|
||||
| Local embeddings fail | Managed Python runtime cannot install or start | See [Troubleshooting clean Linux install](/docs/getting-started/troubleshooting-linux) — usually missing Python 3.13 or an IPv6 proxy env var |
|
||||
| Local embeddings fail | Managed Python runtime cannot install or start | Run `ktx dev runtime status`, then install the local embeddings runtime |
|
||||
| Database test fails | Credentials, network access, database, warehouse, or schema is wrong | Test the same values with the database's native client, then rerun setup |
|
||||
| Context is not built | Setup saved configuration but skipped or interrupted the build | Run `ktx setup` or `ktx ingest --all` |
|
||||
| Agent integration is incomplete | Setup skipped the agents step or installed a different target | Run `ktx setup --agents --target <target>` |
|
||||
|
|
|
|||
|
|
@ -1,163 +0,0 @@
|
|||
---
|
||||
title: Troubleshooting clean Linux install
|
||||
description: Known gotchas when installing KTX from scratch on a clean Linux host (Ubuntu, Debian, container images). Read this before debugging managed-runtime or daemon failures.
|
||||
---
|
||||
|
||||
This page documents the friction a coding agent (or human) will hit when running `npm install -g @kaelio/ktx@next` on a clean Linux host with no Python ≥ 3.13 installed, and during the first `ktx setup` on that host. Each item lists the symptom, the cause, and the exact recovery command.
|
||||
|
||||
## Prerequisites that aren't always satisfied
|
||||
|
||||
KTX needs:
|
||||
|
||||
| Tool | Minimum version | Why |
|
||||
|------|-----------------|-----|
|
||||
| Node.js | 22 | Runs the CLI |
|
||||
| `uv` | 0.5+ | Manages the local Python runtime (semantic-layer daemon, local embeddings) |
|
||||
| Python | 3.13 | KTX's managed Python runtime targets `>=3.13`. The system Python on Ubuntu 24.04 is 3.12. |
|
||||
|
||||
If `uv` is not on `PATH`, install it:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
source $HOME/.local/bin/env # or: export PATH="$HOME/.local/bin:$PATH"
|
||||
```
|
||||
|
||||
Install Python 3.13 via `uv` so it sits alongside whatever the system ships:
|
||||
|
||||
```bash
|
||||
uv python install 3.13
|
||||
```
|
||||
|
||||
You do not need to make 3.13 the system default. KTX's runtime installer will pick it up when you set `UV_PYTHON=3.13` for the install command (see below).
|
||||
|
||||
## Symptom: `ktx dev runtime install` fails on the venv step
|
||||
|
||||
The install log (`~/.ktx/runtime/<version>/install.log`) shows something like:
|
||||
|
||||
```
|
||||
$ uv venv /home/runner/.ktx/runtime/<version>/.venv
|
||||
Using CPython 3.12.3 interpreter at: /usr/bin/python3
|
||||
...
|
||||
Package requires Python >=3.13 but the running Python is 3.12.3
|
||||
```
|
||||
|
||||
**Cause:** `uv venv` picked the system Python (3.12) when it built the runtime virtualenv. KTX's wheels declare `requires-python = ">=3.13"`, so the subsequent install fails.
|
||||
|
||||
**Fix:** install Python 3.13 (above), then force the runtime installer to use it:
|
||||
|
||||
```bash
|
||||
uv python install 3.13
|
||||
UV_PYTHON=3.13 ktx dev runtime install --feature local-embeddings --yes --force
|
||||
```
|
||||
|
||||
The `--force` flag rebuilds the venv. Without it, the failed venv from the previous attempt is reused.
|
||||
|
||||
## Symptom: managed Python daemon crashes immediately with `URL parse error`
|
||||
|
||||
The daemon stderr (`<project>/.ktx/runtime/daemon.stderr.log`) contains an httpx traceback ending in something like:
|
||||
|
||||
```
|
||||
File ".../httpx/_client.py", line 698, in __init__
|
||||
URLPattern(key): None
|
||||
File ".../httpx/_urls.py", line ..., in __init__
|
||||
raise InvalidURL(...)
|
||||
```
|
||||
|
||||
**Cause:** an environment variable holds a value httpx cannot parse — typically `NO_PROXY` or `no_proxy` containing an **IPv6 CIDR** such as `fd07:b51a:cc66:f0::/64`. OrbStack and some Docker network setups inject this by default. httpx interprets every comma-separated entry as a URL pattern and rejects raw IPv6 CIDRs.
|
||||
|
||||
**Fix:** scrub the bad entries before starting the daemon. The simplest workaround is to unset proxy vars entirely for daemon-related commands:
|
||||
|
||||
```bash
|
||||
unset HTTP_PROXY HTTPS_PROXY NO_PROXY http_proxy https_proxy no_proxy
|
||||
ktx dev runtime start --feature local-embeddings
|
||||
```
|
||||
|
||||
If you need proxy entries to remain set for outbound HTTP, keep only the IPv4 + hostname entries:
|
||||
|
||||
```bash
|
||||
export NO_PROXY="localhost,127.0.0.1,*.orb.internal,*.orb.local"
|
||||
```
|
||||
|
||||
This issue is tracked for an upstream fix in the daemon: it should sanitize unparseable entries before constructing httpx clients.
|
||||
|
||||
## Symptom: `ktx setup` keeps connecting to an old daemon port
|
||||
|
||||
Running `ktx setup` more than once can leave orphan `ktx-daemon` processes. Each `setup` invocation may spawn a fresh daemon on a new port and write a new `daemon.json`, while the old one keeps running. Subsequent setup attempts may pick the stale port and fail with a connection-refused error or a `500` health check.
|
||||
|
||||
**Fix:** stop all daemons and remove the state files before re-running setup:
|
||||
|
||||
```bash
|
||||
pkill -9 -f ktx-daemon || true
|
||||
rm -f ~/.ktx/runtime/*/daemon.json
|
||||
rm -f /path/to/project/.ktx/runtime/daemon.json
|
||||
```
|
||||
|
||||
Then start the daemon explicitly **before** re-running setup so `setup` reuses it:
|
||||
|
||||
```bash
|
||||
unset HTTP_PROXY HTTPS_PROXY NO_PROXY http_proxy https_proxy no_proxy
|
||||
ktx dev runtime start --feature local-embeddings
|
||||
```
|
||||
|
||||
## Symptom: `ktx status --json` reports a connection as failed but `ktx connection test <id>` passes
|
||||
|
||||
`ktx status` may cache a failure record from a prior bad run (for example, when the daemon was crashing). A successful `ktx connection test` does not always invalidate the cache.
|
||||
|
||||
**Fix:** re-run a fast ingest, which writes a fresh status record:
|
||||
|
||||
```bash
|
||||
ktx ingest <connection-id> --fast
|
||||
ktx status --json
|
||||
```
|
||||
|
||||
## A minimal "clean Linux install" recipe
|
||||
|
||||
If you only want one working sequence, this one works from a fresh Ubuntu 24.04 container with Node 22 and Claude Code installed:
|
||||
|
||||
```bash
|
||||
# 1. Prerequisites
|
||||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||||
source $HOME/.local/bin/env
|
||||
uv python install 3.13
|
||||
npm install -g @kaelio/ktx@next
|
||||
|
||||
# 2. Pre-warm the managed Python runtime with the right Python
|
||||
UV_PYTHON=3.13 ktx dev runtime install --feature local-embeddings --yes --force
|
||||
|
||||
# 3. Start the daemon with a clean proxy env
|
||||
unset HTTP_PROXY HTTPS_PROXY NO_PROXY http_proxy https_proxy no_proxy
|
||||
ktx dev runtime start --feature local-embeddings
|
||||
|
||||
# 4. Scripted setup (replace DATABASE_URL with your warehouse)
|
||||
mkdir -p /work/project
|
||||
cd /work/project
|
||||
export ANTHROPIC_API_KEY=... # already in env from your Claude Code session
|
||||
export DATABASE_URL=postgresql://...
|
||||
|
||||
ktx setup \
|
||||
--no-input \
|
||||
--yes \
|
||||
--project-dir /work/project \
|
||||
--llm-backend anthropic \
|
||||
--anthropic-api-key-env ANTHROPIC_API_KEY \
|
||||
--anthropic-model claude-sonnet-4-6 \
|
||||
--embedding-backend sentence-transformers \
|
||||
--database postgres \
|
||||
--new-database-connection-id warehouse \
|
||||
--database-url env:DATABASE_URL \
|
||||
--skip-sources \
|
||||
--skip-agents
|
||||
|
||||
# 5. Build schema context
|
||||
ktx ingest warehouse --fast
|
||||
|
||||
# 6. Verify
|
||||
ktx status --json
|
||||
ktx connection test warehouse
|
||||
```
|
||||
|
||||
Success looks like:
|
||||
|
||||
- `ktx status --json` reports `"verdict": "ready"`
|
||||
- `ktx connection test warehouse` exits 0 with `Status: ok`
|
||||
- `semantic-layer/warehouse/_schema/` contains generated YAML files
|
||||
Loading…
Add table
Add a link
Reference in a new issue