Denial reasons

When Midplane denies a query, the MCP tool result and the DECIDED audit row both carry a policy_rule naming the rule that denied, plus a human-readable reason. This page maps each rule to the cause and the fix. The reason is written for the agent. Since 0.18.0 it states the decision and any fix the agent can make to its own statement (add a WHERE clause), and never names a policy key to flip — loosening policy is operator work, which is what the Fix columns below are for. Branch on policy_rule, not on the prose; the rule identifiers are stable, the wording isn’t. The engine evaluates four rules in order, and the first rule that denies wins. The order is parse_error → multi_statement → table_access → dangerous_statement. Two are always-on guards (parse_error, multi_statement); the rest are driven by your policy — table_access and the dangerous_statement guardrails default on. See the policy engine.

`policy_rule`	Default	Cause
`parse_error`	Always on	The SQL didn’t parse.
`multi_statement`	Always on	More than one statement in one query.
`table_access`	On (`read`)	A read or write the table’s access level doesn’t grant.
`dangerous_statement`	On (`0.9.0+`)	A whole-table write (no `WHERE`) or a DDL statement, regardless of `table_access`.

Two more policy_rule values come from the write-approvals stage, which runs after all four rules allow.

`table_access`

A query referenced a table at a permission level its policy doesn’t grant. A query is denied if any referenced table fails — including writes hidden in CTEs, subqueries, UNION arms, or JOINs, caught by the recursive AST walk. There are three sub-cases:

Cause	Fix
Write blocked — a write (`INSERT` / `UPDATE` / `DELETE`) to a table that’s `read`.	Mark the table `read_write` in `table_access.tables`.
Read blocked — a `SELECT` from a table that’s `deny`.	Mark the table `read` (or `read_write`).
No target / unlisted — the table falls through to a `default` that denies the access (`default: deny`, or a write under `default: read`).	Add a per-table override, or raise the `default` (carefully).

-- with table_access.tables.users = read:
DELETE FROM users WHERE id = 1     -- DENY (users is read; writes need read_write)
SELECT * FROM audit_log            -- DENY (audit_log is deny; no access at all)

To grant the write, mark the table read_write:

table_access:
  default: read
  tables:
    users: read_write

Run midplane policy test to confirm the change before you ship it.

`multi_statement`

The query contained more than one top-level statement. Midplane allows exactly one statement per query — stacked statements (the classic SQL-injection vector) never reach the database.

SELECT 1; DROP TABLE users;   -- DENY (2 statements)
SELECT 1;                     -- ALLOW (trailing semicolon, still 1 statement)

Fix: split the query into one statement per call. A trailing semicolon is fine; a second statement is not.

`dangerous_statement`

A guardrail denied a write categorically — regardless of table_access, so this fires even on a table you’ve marked read_write. One guard per write class, each independently toggled:

Cause	Guard	Default	Fix
Whole-table write — a `DELETE` / `UPDATE` with no `WHERE` clause.	`block_unqualified_dml`	On (`0.9.0+`)	Add a `WHERE` that scopes the rows you intend to change, or set the flag `false`.
Schema change (DDL) — a `DROP`, `TRUNCATE`, or `ALTER`.	`block_ddl`	On (`0.9.0+`)	Run the DDL out-of-band, or set the flag `false`.
Row change — an `INSERT` / `MERGE`, or an `UPDATE` / `DELETE` with a `WHERE`. Also `CREATE TABLE`, `CREATE TABLE AS`, `CREATE INDEX`, and `SELECT … INTO`.	`block_dml`	Off (`0.17.0+`)	Set the flag `false` to allow writes, or move the class to ask with `approvals.row_changes`.

DELETE FROM orders            -- DENY (no WHERE — whole-table write)
DELETE FROM orders WHERE id=1 -- qualified: denied only when block_dml is on
DROP TABLE orders             -- DENY (DDL)

The agent-facing message names the operation and which guardrail fired, for example:

Midplane denied this query because this DELETE on `orders` has no WHERE clause,
which would affect every row in the table. Add a WHERE clause that scopes the rows
you intend to change. This guardrail blocks whole-table writes regardless of
table-access policy.

Because the guardrail runs last, a statement another rule would also deny (for example a DROP under the no-YAML deny-all-writes default) surfaces that other rule’s reason instead — the statement is blocked either way. See the guardrails schema.

`parse_error`

The input failed to parse. libpg_query, the real Postgres parser, decides this — anything that isn’t valid Postgres SQL is denied. Midplane never enforces policy on text it can’t read. Fix: rewrite the query as valid Postgres SQL. Midplane parses with the Postgres parser, so dialect-specific or exotic syntax it doesn’t recognize is denied — rewrite it into a supported form.

Write approvals

Write approvals run after the four rules allow (0.16.0+), so these only ever appear on a statement your policy already permits. Two of the four outcomes are real decisions and are audited as DECIDED(DENY); the other two are non-decisions — nothing ran and nobody refused, so no DECIDED row is written and no deny webhook fires.

`policy_rule`	Decision?	What happened	What to do
`approval_denied`	Yes	A human refused the write, and their note (when they left one) is in the `reason`.	Write a different statement — retrying the same one only opens a new request.
`approval_expired`	Yes	Nobody answered before the request’s deadline.	Re-run the identical statement to ask again.
`approval_pending`	No	The request is open and waiting on a human. Carries an `approval_id`, a deadline, and the resume contract.	Poll `check_approval`, then re-run the identical statement once it reads `approved`.
`approval_unavailable`	No	The approval service couldn’t be reached. Nobody denied this — a 401 from a misconfigured gate must never read as a refusal.	Retry. If it persists, the deployment’s gate needs fixing.

Both non-decisions return executed: false first: an agent that reads a hold as success would report a write that never happened.

Result masking

column_masking is not one of the ordered policy rules above — those decide whether a query runs. It fires when the engine can’t safely apply column masking to a query that touches a masked table, failing closed: the query is denied before it runs and all rows withheld rather than risk returning an unmasked value.

`policy_rule`	When	Behavior
`column_masking`	A query references a masked table in a shape the engine can’t safely rewrite — a view over a masked table, a whole-row or composite serialization (`to_jsonb(users)`, `row_to_json`), an opaque or dynamic-SQL function (`query_to_xml`, `dblink`, a UDF), a system column, or a stale catalog.	Fail-closed — the query is denied before execution, every row withheld, nothing leaks.

Plain aggregates and joins over a masked table are not denied — they rewrite and run. The agent-facing message hints at the fix: query the masked column directly rather than through a view, a whole-row serializer, or an opaque function, so the engine can mask it at the source. See column masking for the mechanic and transforms.

Still stuck?

If a query is denied and you can’t tell why, dry-run it with midplane policy test — it prints the deciding rule and the exact agent-facing message against your policy file, with no database connection. For more, see troubleshooting.

Troubleshooting

Common denials, connection problems, and agent-wiring issues.

Configuration

Protocol & data

`table_access`

`multi_statement`

`dangerous_statement`

`parse_error`

Write approvals

Result masking

Still stuck?

Troubleshooting

​table_access

​multi_statement

​dangerous_statement

​parse_error

​Write approvals

​Result masking

​Still stuck?

Troubleshooting

`table_access`

`multi_statement`

`dangerous_statement`

`parse_error`

Write approvals

Result masking

Still stuck?