Skip to main content

When a compliance module refuses

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.

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, carrying the module instance address, module type, machine-readable reason code, and message. First-generation (V1) modules fail with DALP-1009, carrying plain text only. The contract error reference documents both error envelopes.

A plain transfer or mint can also fail before module details surface: DALP-1096 for a transfer and DALP-1110 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 (no approval), DALP-4035 (expired), DALP-4034 (single use spent), DALP-4423 (amount exceeded), DALP-4118 (unregistered identity), DALP-1093 (approver removed)
Identity verification
DALP-4266 (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

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.

Was this page helpful?