# When a module refuses

Source: https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-module-refusals
What a compliance module's refusal returns, how to find the module that refused, and what to check when a module does not behave as expected.

When a compliance module refuses a transfer, mint, or burn, the transaction reverts before balances change. This reference maps refusal errors and reason codes to their owning module and explains how to diagnose unexpected refusals. For each module's parameters and behaviour, see [Compliance modules](https://docs.settlemint.com/docs/concepts/compliance-and-identity/compliance-modules).

## When a module refuses [#when-a-module-refuses]

Detailed module errors identify the refusing rule directly, while generic transfer or mint rejections require simulation to isolate the blocker.

Second-generation (V2) modules fail with [DALP-1120](https://docs.settlemint.com/docs/api-reference/errors), carrying the module instance address, module type, machine-readable reason code, and message. First-generation (V1) modules fail with [DALP-1009](https://docs.settlemint.com/docs/api-reference/errors), carrying plain text only. The [contract error reference](https://docs.settlemint.com/docs/api-reference/errors/error-code-reference) documents both error envelopes.

A plain transfer or mint can also fail before module details surface: [DALP-1096](https://docs.settlemint.com/docs/api-reference/errors) for a transfer and [DALP-1110](https://docs.settlemint.com/docs/api-reference/errors) for a mint. A recipient missing from the asset's identity registry is refused before queueing with `identity-not-registered`. Any other generic refusal omits the reason code, so run **Transfer pre-check** to inspect the exact blocker.

Two modules emit dedicated error codes instead of generic compliance reason codes:

| Module | Error codes |
| --- | --- |
| Transfer approval | [DALP-4036](https://docs.settlemint.com/docs/api-reference/errors) (no approval), [DALP-4035](https://docs.settlemint.com/docs/api-reference/errors) (expired), [DALP-4034](https://docs.settlemint.com/docs/api-reference/errors) (single use spent), [DALP-4423](https://docs.settlemint.com/docs/api-reference/errors) (amount exceeded), [DALP-4118](https://docs.settlemint.com/docs/api-reference/errors) (unregistered identity), [DALP-1093](https://docs.settlemint.com/docs/api-reference/errors) (approver removed) |
| Identity verification | [DALP-4266](https://docs.settlemint.com/docs/api-reference/errors) (recipient not verified, without listing missing topics) |

Most V2 reason codes map to one module, while the count modules share theirs:

| Module | Reason code |
| --- | --- |
| Block addresses | `COMPLIANCE_CHECK_REASON_ADDRESS_BLOCKED` |
| Claim expiry | `COMPLIANCE_CHECK_REASON_CLAIM_EXPIRED` |
| Claim expiry | `COMPLIANCE_CHECK_REASON_CLAIM_MISSING` |
| Country block list | `COMPLIANCE_CHECK_REASON_COUNTRY_BLOCKED` |
| Country allow list | `COMPLIANCE_CHECK_REASON_COUNTRY_NOT_ALLOWED` |
| Issuance volume limit | `COMPLIANCE_CHECK_REASON_EXCEEDS_QUOTA` |
| Capital raise limit | `COMPLIANCE_CHECK_REASON_EXCEEDS_RAISE_LIMIT` |
| Supply cap | `COMPLIANCE_CHECK_REASON_EXCEEDS_SUPPLY_CAP` |
| Wallet count | `COMPLIANCE_CHECK_REASON_EXCEEDS_COUNTRY_LIMIT` |
| Identity count | `COMPLIANCE_CHECK_REASON_EXCEEDS_COUNTRY_LIMIT` |
| Wallet count | `COMPLIANCE_CHECK_REASON_EXCEEDS_TOTAL_LIMIT` |
| Identity count | `COMPLIANCE_CHECK_REASON_EXCEEDS_TOTAL_LIMIT` |
| Identity block list | `COMPLIANCE_CHECK_REASON_IDENTITY_BLOCKED` |
| Identity allow list | `COMPLIANCE_CHECK_REASON_IDENTITY_NOT_ALLOWED` |
| Collateral requirement | `COMPLIANCE_CHECK_REASON_INSUFFICIENT_COLLATERAL` |
| Time lock | `COMPLIANCE_CHECK_REASON_INSUFFICIENT_UNLOCKED` |
| Lock-up | `COMPLIANCE_CHECK_REASON_LOCKED_UNTIL` |
| Minimum holding | `COMPLIANCE_CHECK_REASON_RECIPIENT_BELOW_MINIMUM_HOLDING` |
| Minimum holding | `COMPLIANCE_CHECK_REASON_SENDER_BELOW_MINIMUM_HOLDING` |
| Own custody gateway | `COMPLIANCE_CHECK_REASON_NOT_OWN_CUSTODY_GATEWAY` |
| Wallet restriction | `COMPLIANCE_CHECK_REASON_WALLET_RESTRICTED` |

Four modules share one reason code when the receiver has no registered identity:

| Module | Reason code |
| --- | --- |
| Country allow list, Country block list, Identity allow list, Identity count | `COMPLIANCE_CHECK_REASON_IDENTITY_UNKNOWN` |

Capital raise limit also fails closed on missing or invalid pricing, with one code per cause (a missing price feed returns the price resolver's own error without a reason code):

| Cause | Reason code |
| --- | --- |
| The rule holds no price resolver address | `COMPLIANCE_CHECK_REASON_NO_PRICE_RESOLVER` |
| The resolver returns a zero or negative price | `COMPLIANCE_CHECK_REASON_NO_VALID_PRICE` |
| The resolver's price is stale | `COMPLIANCE_CHECK_REASON_STALE_PRICE` |

Token supply limit stays on plain-text V1 errors with no reason code. Time lock can also emit two internal bookkeeping codes that represent platform faults to escalate rather than party refusals:

| Cause | Reason code |
| --- | --- |
| The module's stored batches could not be updated safely during removal. | `COMPLIANCE_CHECK_REASON_TOKEN_REMOVAL_FAILED` |
| A legacy token's time-lock batches are not bound to this compliance engine. | `COMPLIANCE_CHECK_REASON_UNSAFE_LEGACY_TOKEN` |

A refusal reflects live rules and on-chain state, not a transient fault, so retrying unchanged fails again. Update the underlying condition first: adjust a list entry, re-issue an expired claim, wait for a window rollover, edit a limit, or adjust the amount. A burn restores capacity only on modules that credit burns (capital raise limit never does).

Before retrying, open the token's **Transfer pre-check** tab (visible to asset freeze holders, System managers, Identity managers, Verification issuers, and Compliance managers). Enter the **Sender**, **Recipient**, and **Amount**, then select **Run check** to simulate the transfer and see blockers grouped by who can resolve them.

## Troubleshooting [#troubleshooting]

**A module you expect is not offered**

The Console filters the catalogue to modules compatible with the surface's module-set generation and hides modules
already enabled there. A second-generation module does not appear on a first-generation policy template, and a module
the token already carries is not offered twice.

**A configured field cannot be changed**

Some fields lock once the module is enabled: the issuance volume limit's period length and window mode, the time
lock's hold period, the transfer approval mode, and every parameter of the capital raise limit. The Console marks the
locked field. To use a different value, remove the module and install a new instance. The new instance starts with no
memory of what the old one had tracked.

**Adding the capital raise limit, or creating an asset with it, fails**

The module converts mint amounts to fiat through the price resolver add-on. While the system lacks that add-on,
creating an asset with the rule, adding it to a token, and adding it as a global control are all refused with
`compliance.price.RESOLVER_MISSING`. Install the add-on first, then try again. A request that names its own price
resolver and price topic for the rule keeps them and is not refused.

**A refusal names a rule no token-level module explains**

Check the rows marked "Global" in the **Rules** table of the token's **Compliance** tab. Global controls apply to the
token automatically, refuse operations the same way its own rules do, and show "Set in Compliance › Global controls"
in the Setting column. Change them in global controls, not from the token.

**A country sits on both the allow list and the block list**

No holder in that country can satisfy both rules, so an ordinary transfer or mint to that receiver fails when both
rules apply. If every allowed country is also blocked, no country passes. Check for overlap between the country allow
list and the country block list before deploying both on the same token.

