Troubleshooting

Most SeeKi problems surface at start-up, and most of those are one of five recurring shapes. This page walks through each one in the order you're likely to meet it — what the log line looks like, why it happens, and the calm fix.

Before you dig

Re-run with RUST_LOG=seeki=debug. The extra lines often point straight to the cause. See Logs for the full filter syntax.

Connection refused

Error: connection refused (os error 111) — host "db.internal" port 5432

SeeKi reached the network and got back a polite "nothing is listening here." Two likely causes:

  • The database isn't running. Start it, then restart SeeKi.
  • The host or port in [database] url is wrong. Double-check the connection string against the database's actual bind address.

If the database is on a remote machine behind a bastion, you probably want an SSH tunnel rather than a direct connection.

Address already in use

Error: Address already in use (os error 98) — 127.0.0.1:3141

Something else owns port 3141. Usually a previous SeeKi process that didn't exit cleanly, or another local service. Find it and decide what to do:

lsof -iTCP:3141 -sTCP:LISTEN
# or
ss -ltnp | grep :3141

Stop the process, or change SeeKi's port in [server]:

[server]
port = 3142

SSH key permissions

Error: permissions 0644 for '/home/you/.ssh/id_ed25519' are too open

OpenSSH and the SSH library SeeKi uses both refuse to load a private key that's readable by anyone else on the machine. Fix the mode:

chmod 0600 ~/.ssh/id_ed25519

Confirm:

ls -l ~/.ssh/id_ed25519
# -rw------- 1 you you …

Passphrase-protected keys

If the key has a passphrase, set ssh.key_passphrase in .seeki.secrets — not in seeki.toml. See Config locations.

Config parse errors

Error: Invalid config at seeki.toml: TOML parse error at line 7, column 8
  expected `=`, found `"`

The TOML is malformed. SeeKi names the path and line so you can go straight to it. Common culprits:

  • A value not wrapped in quotes (url = postgres://… instead of url = "postgres://…").
  • A trailing comma inside an inline table or array.
  • Mixing tabs and spaces — TOML is forgiving, but some editors insert odd characters.

A one-liner to double-check without starting SeeKi:

python3 -c "import tomllib; tomllib.load(open('seeki.toml','rb')); print('ok')"

When SeeKi hits an invalid config, it exits rather than silently entering setup mode — so a bad file never looks like a missing file.

Table not found

GET /api/tables/vehicles_log/rows → 404 "table not found"

The table exists in the database but SeeKi isn't exposing it. Two places to check:

  1. [tables] include is set and doesn't list this table. Either add it, or remove include entirely to expose every table.
  2. [tables] exclude lists it. Remove it from exclude.

If the table appears in both include and exclude, SeeKi warns at start-up and excludes it:

WARN seeki: table appears in both [tables] include and exclude
           — it will be excluded  table=audit_log

Restart SeeKi after editing the config — [tables] is read once at boot.

Still stuck?

Capture a debug run and file an issue. SeeKi is small enough that the author can usually recognise a log excerpt on sight.

RUST_LOG=seeki=debug,tower_http=debug ./seeki 2>&1 | tee seeki-debug.log