None of the warnings below require action unless stated otherwise — they're listed here so they don't alarm new users.
'SHOW TRANSACTION ISOLATION LEVEL' contains unsupported syntax. Falling back to parsing as a 'Command'.
When: During process-history with a PostgreSQL connector.
Why: pg_stat_statements records every query the database sees, including internal driver handshake queries (e.g. psycopg2 checking session settings). sqlglot doesn't recognise PostgreSQL SHOW commands and logs this before falling back to a generic representation.
Risk: None — these rows are discarded by the filter step before they can influence the knowledge base.
Action: None required.
Warning: You are sending unauthenticated requests to the HF Hub.
When: First run of any embedding-dependent command (--embed, doc-ingest, semantic cache warm-up). Does not appear on later runs once the model is cached.
Why: The all-MiniLM-L6-v2 sentence-transformer model downloads from Hugging Face Hub on first use and is cached at ~/.cache/huggingface/hub/. Without HF_TOKEN, the download is unauthenticated and subject to shared rate limits.
Risk: Low — the model downloads once and is cached permanently. The only real risk is a 429 rate-limit error during the initial download.
Action recommended: Set a free Hugging Face token (Settings → Access Tokens → New token, Read access) via HF_TOKEN=hf_.... Not needed once the model is cached.
Connection refused (os error 111)
# Windows: [WinError 10061] No connection could be made because the target machine actively refused it
When: --embed is passed to process-history, or the semantic cache tries to connect, and Qdrant isn't running.
Risk: None to your data — pipeline stages before the embed step already completed; only the Qdrant upload was skipped.
Action: Start Qdrant (see qdrant-setup), or rerun with --no-embed to continue without it.
failed to connect to the docker API at npipe:////./pipe/dockerDesktopLinuxEngine
When: Any docker command on Windows when Docker Desktop is installed but not started.
Action: Open Docker Desktop and wait for the whale icon in the system tray to stop animating. Alternatively, use the native Qdrant binary (qdrant-setup), which needs no Docker at all.
Could not resolve authentication method. Expected one of api_key, auth_token, or credentials to be set.
When: --annotate runs (or defaults on) with no LLM API key set.
Why: NLQueries defaults to Anthropic. Setting OPENAI_API_KEY alone does not switch the provider — you also need LLM_PROVIDER=litellm and LLM_MODEL=openai/gpt-4o.
Action:
# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
# OpenAI
export LLM_PROVIDER=litellm
export LLM_MODEL=openai/gpt-4o
export OPENAI_API_KEY=sk-proj-...
To skip annotation entirely, use --no-annotate.
UserWarning: Core Pydantic V1 functionality isn't compatible with Python 3.14 or greater.
Status: resolved. Earlier builds imported langchain_text_splitters for document chunking, which pulled in a pydantic.v1 compatibility shim that emitted this warning on Python 3.14+.
NLQueries no longer depends on LangChain anywhere. Query routing is plain async dispatch (no langgraph/langchain_core), and document ingestion now uses a small built-in text splitter — so no command imports langchain, and the warning no longer occurs on any Python version.
NLQueries targets Python 3.11 and 3.12; pyproject.toml caps requires-python at <3.14, so pip install won't select an unsupported interpreter. Python 3.14+ is not supported yet — use 3.11 or 3.12:
python3.12 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -e ".[dev]"
Loading weights: 100%|████████████████| 103/103 [00:00<00:00, 12833.48it/s]
When: Every command that uses embeddings, even after the model is already downloaded.
Why: Each CLI invocation is a fresh process with no shared memory, so the ~80 MB model loads from local disk cache every time. This completes in well under a second.
Risk: None — loading from local cache, not downloading.
Action: None required. If startup time matters, run the embedding daemon (nlqueries embed-server start) — it keeps the model resident so each embedding call takes ~10 ms instead of reloading from disk on every command. See qdrant-setup and cli-reference for the daemon commands.