mirror of
https://github.com/Kaelio/ktx.git
synced 2026-06-13 08:15:14 +02:00
2403f58eff
- Pin managed Python runtime to 3.13 via `uv venv --python 3.13` so installs don't pick the system 3.12 on Ubuntu 24.04 and fail at wheel install. - Sanitize NO_PROXY/no_proxy for the daemon child process — drop IPv6 CIDR entries that httpx rejects with InvalidURL (OrbStack injects these by default). - Add `enabled_tables` allowlist on warehouse connections (zod schema + live-database introspection filter) to scope ingest to specific tables. - Add `getting-started/troubleshooting-linux` docs page covering the Python 3.13 prerequisite, IPv6 proxy gotcha, and a minimal working recipe; link it from the quickstart troubleshooting table and the llms-docs map. - Make docs-site origin overridable via `KTX_DOCS_ORIGIN` so local builds can serve under host.docker.internal.
163 lines
6 KiB
Text
163 lines
6 KiB
Text
---
|
|
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
|