state_cap_table_invariant_violated

Last updated Jun 14, 2026

Cause

Matter enforces a closed set of cap-table invariants on every mutation that touches equity — grants, exercises, repurchases, dilutions, secondary sales, conversions. state_cap_table_invariant_violated fires when the proposed mutation would result in a cap-table state that breaks one of these invariants. Examples include issuing shares that exceed the authorised-shares ceiling, awarding grants that exhaust the plan headroom, executing a secondary that drops a stockholder's holdings below zero, or converting a SAFE at a discount that produces fractional shares the share-class doesn't permit.

The check runs inside the cap-table CQRS write path before the change is materialised. The mutation is rejected wholesale — no partial writes — so the cap table at rest always satisfies the invariants. The detail field names the specific invariant that would fail.

Fix

1. Read the detail field. It names the invariant (authorized_shares_ceiling, plan_headroom_exhausted, holdings_below_zero, share_class_disallows_fractional).
2. For authorised-shares ceiling, increase the ceiling via a board-authorised amendment (createResolution + the relevant entity-level operation).
3. For plan-headroom exhaustion, amend the EquityPlan to enlarge the headroom or cancel unissued grants to free capacity.
4. For fractional share issues, round to the share class's minimum unit and surface the rounding decision to the human stakeholder before retrying.

Related codes

• state_authorisation_required — the operation needs a Resolution before it can run.
• state_transition_invalid — the resource cannot make the transition at all.
• validation_body_invalid — the input itself was malformed.

API reference

• Cap table — /api-reference/cap-table
• Equity plans — /api-reference/equity-plans