Faz Docs

An index of the error families faz emits, with the literal error text and links to detailed fixes.

This page is the entry point for "I see an error message — where do I go?" Find your error string below, click through to the detailed fix, and move on.

For specific scenarios, the four sibling pages each cover one failure mode:

Connection failed — faz can't reach a database.
Query blocked — a query reached faz but was rejected.
MCP not loading — your AI client can't see faz.

Everything else lives below.

Server startup

`no faz.yaml or database.yaml in <project_root>`

no faz.yaml or database.yaml in /home/you/myproject. Run `faz init` to generate a starter faz.yaml.

faz couldn't find a config file. Run faz init in the directory you want, or set FAZ_CONFIG=/absolute/path/to/faz.yaml.

`<file>.yaml must be a mapping at the top level`

The YAML file is a list, a string, or some other non-mapping. The top-level shape must be a dict with databases: (and usually permissions: and safety:) keys.

`unknown connector type 'X'`

unknown connector type 'mariadb'. Valid types: ['postgresql', 'mysql', 'oracle', 'mongodb', ...]

The type: value in your databases: entry isn't one of the 14 supported connector types. See faz.yaml for the full list.

`permissions[N] (database=X) has unknown access level 'Y'`

permissions[0] (database=<database>) has unknown access level 'none'. Valid: ['R', 'W', 'RW', 'RA', 'RWA', 'A']

You used a non-existent access code (commonly none, which doesn't exist as a value). See Permission levels for the six valid codes; for "deny reads on a single table while leaving the rest readable," see Blocking a table from reads.

`permissions[N] (database=X) missing required 'access' field`

Every entry in the permissions: list needs both database: and access: keys. The tables: map is optional. See faz.yaml.

`Duplicate connector name 'X'`

Two database entries share the same name. The last one wins, and faz emits a warning. Add an explicit name: to disambiguate:

databases:
  - name: pg_primary
    type: postgresql
    # ...
  - name: pg_replica
    type: postgresql
    # ...

`FAILED to connect <name>`

WARNING: FAILED to connect <database> — could not connect to server: Connection refused. Continuing without it.

The connector raised an exception during startup. faz logs it at WARNING and continues — the database appears in /v1/databases with reachable: false and the exception text in error. Full diagnosis on Connection failed.

Query-time

Block envelopes

When the safety pipeline blocks, the response has shape:

{
  "status": "blocked",
  "error": {
    "stage": "PROMPT_GUARD" | "RBAC_GATE" | "AST_CHECKER" | "INJECTION_ANALYSER",
    "reason": "<specific message>",
    "suggestion": null
  }
}

The stage field tells you which check rejected it. Each stage's specific block messages and fixes are on Query blocked.

`unknown database: '<typo>'. Configured: ['<database-1>', '<database-2>']`

The database field in your request doesn't match any databases: entry's name. Check the spelling against faz policy output.

`step 'sN' depends on unknown or forward-referenced step 'sM'`

In a federated query, a step's depends_on references a step ID that either doesn't exist or appears later in the steps[] list. faz enforces strict topological order — fix the ordering or correct the reference.

`duplicate step_id: 's0'`

Two steps in a federated query reuse the same step_id. Each must be unique within the request.

`Merge SQL failed: ...`

The DuckDB merge SQL had a syntax error or referenced a non-existent step table. The merge runs in DuckDB; consult its error text for the specific problem. Common: typo in a step alias (s0 vs s_0), or a join condition referencing columns that don't exist in the per-step results.

Empty results when you expected rows

Two common causes:

Partial denial silently stripped a step. If you ran a federated query and one of the steps' tables wasn't permitted by permissions:, that step was silently dropped. Check audit.jsonl's rbac.stripped field to see which.
Guardrails injected a LIMIT smaller than your data. If the query naturally returned 5,000 rows and your safety.max_rows_per_query is 1000, you got the first 1,000. Increase the row cap in faz.yaml (with a restart) or paginate via GET /v1/results/{request_id}.

Audit log

`Failed to write audit file: [Errno N] ...`

WARNING faz.audit: Failed to write audit file: [Errno 28] No space left on device

faz couldn't write to the audit JSONL. The query proceeded — audit failure doesn't block requests — but the entry is missing from the file. Free disk space, fix the path, or rotate the file. If you ship audit logs to a SIEM for compliance, monitor for this warning so a silently failing audit doesn't leave you blind.

MCP

For "Claude/Cursor/OpenClaw doesn't see faz," see MCP not loading.

Still stuck?

Run faz policy to confirm faz.yaml parses.
Run faz test to confirm every database is reachable and the policy works as expected.
Tail the audit log: faz logs --follow (it has the trace_id, transport, and per-stage outcomes).
File an issue at github.com/fazhq/faz with the trace_id, the query you ran, and the relevant audit entry.

Connection failed — database connection diagnosis.
Query blocked — per-stage block messages and fixes.
MCP not loading — when an MCP client can't see faz.
Audit log — the schema and how to grep it.

Common Errors