---
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