Skip to content
Home › Reference › Troubleshooting › FAQ

FAQ

The most-asked questions, in roughly the order new users hit them.

Installation

How do I install AMX?

pip install amx-cli

That's the only command. The install includes the CLI, the multi-agent runtime, and the LLM SDKs. Only the DuckDB driver ships by default; every other backend installs its driver on first use, which needs network access. On an air-gapped machine, pre-install the driver for your backend while you still have connectivity.

Multiple amx binaries on PATH

/doctor reports every amx it finds. Usually this means one is in your global pip install and another is in a project venv. Pick one and uninstall the other, or use a venv consistently.

Configuration

Where does AMX store secrets?

In the OS keychain when available (macOS Keychain, Windows Credential Manager, Linux Secret Service via libsecret). The YAML stores a reference, not the secret. On headless Linux without a keychain, secrets fall back to ~/.amx/config.yml itself with mode 0o600.

ConfigSchemaTooNewError

Your AMX binary is older than the config schema in ~/.amx/config.yml. Upgrade:

pip install --upgrade amx-cli

If you need to downgrade (e.g. team-wide pin), AMX refuses to load the newer config rather than mangling it. Either roll back the schema by hand (delete the keys from the newer schema version, decrement schema_version) or stand up a separate config with amx --config /path/to/old.yml.

Can I share a config across machines?

Yes — amx --config /path/to/team.yml reads any file. But secrets stored in the OS keychain don't travel with the YAML; each machine needs its own keychain entries (or falls back to inline secrets).

Running

/run failed with "LLM unreachable"

/run tests the active LLM before profiling any asset and stops if the model/profile is unreachable or deactivated. Run /doctor — it'll tell you whether the API key is invalid, the endpoint is unreachable, or the model is deactivated.

/run returned 0 visible characters and used all output tokens

This is the reasoning-route token-budget exhaustion message. The model burned the whole budget on internal thinking. AMX auto-raises max_tokens to a 32 768-token floor for recognised reasoning routes (Kimi K2.x, Claude extended-thinking, GPT-5 / o-series, DeepSeek-reasoner, OpenRouter thinking variants), but if you see this, your model isn't recognised. Override the floor manually:

export AMX_LLM_MIN_MAX_TOKENS=65536

Use a larger value if the model keeps hitting the ceiling. See LLM Providers — Reasoning models for the full list of recognised reasoning routes.

finish_reason=length on every column

The prompt + expected output is bigger than the model's max_tokens. AMX never silently parses truncated JSON — the run halts. Either:

  • Reduce /llm-batch-size N so fewer columns go in one prompt.
  • Drop /n-alternatives to 1.
  • Switch /prompt-detail to minimal.
  • Or raise max_tokens if the provider supports it.

/run is slow on a wide schema

Switch profiling to sampled or metadata. Use /run --batch for overnight async runs. See Batch mode and Profiling modes.

Why is the suggestion confidence lower than I expected?

A few causes:

  • Anthropic Batch results don't have logprobs — they fall back to model-declared confidence which tends to be conservative.
  • The RAG and Code agents had no evidence for this column — without external evidence, the merge step trusts the Profile Agent alone, which lowers calibrated confidence.
  • Logprob thresholds are tuned high. /llm-thresholds 0.85 0.6 is the default; lower it if you want more rows to land in the high band.

Backends

Can AMX write back to a read-only DB profile?

No. The /apply step needs write privileges. Use a separate profile for write-back: amx_reader for /run, amx_writer for /apply. Or grant COMMENT privilege to your read profile.

Why is shared mode blocked for ClickHouse / DuckDB?

ClickHouse cannot UPDATE rows the way finish_run requires. DuckDB is a local file, not shared storage. Both are blocked at Enable time with a clear error listing the supported backends.

Databricks CERTIFICATE_VERIFY_FAILED

Set a tls_trusted_ca_file on the Databricks DB profile, or set AMX_DATABRICKS_TRUSTED_CA_FILE. See Databricks and TLS and proxies.

/ask

/ask says "no active LLM profile"

/ask fails closed when no LLM is configured. Run /llm → /add-llm-profile <name>.

/ask returned an empty result table

You probably asked a broad semantic question against a schema with no generated descriptions yet. Either run /analyze run against the schema first, or rephrase the question to use exact identifiers (/ask what is the ADRC table?).

/ask answered in the wrong language

/search answer language is forced to the detected language of your question. If detection misfires, prefix your question with the language explicitly: /ask in English, which tables ….

History and storage

Where is ~/.amx/history.db?

On macOS / Linux: /Users/<name>/.amx/history.db. On Windows: C:\Users\<name>\.amx\history.db.

Override with AMX_CONFIG_DIR=/some/other/path (Linux/macOS) or by setting your home directory explicitly.

Can I delete history.db to start over?

Yes, but you'll lose run history, the search catalog, and all session memory. The next amx start recreates an empty database. config.yml is unaffected.

My teammate's runs aren't visible in /history list

/history list reads from your local ~/.amx/history.db only. To see the team's runs, both you and your teammate need to have run /history-store enable against the same shared backend (PostgreSQL / Snowflake / MySQL / MSSQL / Redshift / Databricks), and then /history-store list-team surfaces the cross-machine view from the shared schema. Plain /history list stays local on purpose so the per-user audit trail is always authoritative even when the team store is offline.

Where to ask more