Troubleshooting | SAG Wiki

When troubleshooting SAG, first distinguish between an unready service, an unready document, unavailable models, and a broken browser-to-API network path. The sections below follow the most common symptoms.

The page does not open

docker compose ps
docker compose logs --tail=200 web api

Verify that no other process occupies the Web port and that web waits for a healthy api. A custom WEB_PORT changes only the host port, not port 3000 inside the container.

API health succeeds but ready fails

/system/health checks only the process. /system/ready also checks critical initialization. Inspect API logs for database connections, schema setup, data-directory permissions, and engine-configuration errors.

In a PostgreSQL override environment, also run:

docker compose \
  -f compose.yaml \
  -f compose.postgres.yaml \
  ps

Confirm that db is healthy and that the password, database name, and connection string agree.

A document remains in processing

Inspect the document status, progress, and error.
Query the corresponding /jobs/{job_id}.
Verify Embedding and LLM independently.
For PDFs using MinerU, check the key, version, and polling timeout.
Reprocess a failed job instead of repeatedly uploading the same file.

SAG falls back to MarkItDown when MinerU is unavailable or fails, but layout-heavy PDFs may produce a different result.

Fast retrieval returns nothing

The document must be ready.
Embedding must be configured and vectorization complete.
Test known content within the correct source scope first.
Reprocess old documents after changing the Embedding model.

Increasing top_k cannot repair a missing index or incompatible semantic spaces.

Precise mode or conversations fail

Precise mode needs an LLM for query understanding and reranking. Conversations also need a generation model. Run connection tests in Settings and verify provider, base URL, model name, timeout, and key.

An interface that opens does not mean model configuration is complete; this is expected behavior.

The browser reports a network or CORS error

Check these values:

SAG_CORS_ORIGINS=https://web.example.com
NEXT_PUBLIC_API_BASE=https://api.example.com
BIND_ADDRESS=0.0.0.0

Rebuild Web after changing NEXT_PUBLIC_API_BASE. The reverse proxy must also handle OPTIONS, Authorization, and long-lived SSE connections correctly.

MCP cannot connect

The URL should end in /mcp/.
HTTP requests need Authorization: Bearer <TOKEN>.
When using source_id, confirm that the current identity owns that source.
Call list_sources first to verify connection scope and authentication.

A citation does not open

Confirm that the corresponding document was not deleted or reprocessed into new chunk IDs. External systems should save explainable source metadata with a citation but must not assume that a chunk ID survives deletion and reconstruction forever.

Still unresolved

Before filing an issue, include the SAG version, runtime method, operating system, minimal reproduction steps, and sanitized logs. Never upload JWTs, model keys, database passwords, or private document content.