> ## Documentation Index > Fetch the complete documentation index at: https://shield.fi/docs/llms.txt > Use this file to discover all available pages before exploring further. # Failures and recovery > How to diagnose rejected swaps, ambiguous record state, and failed output claims. Recovery starts by identifying the order's actual on-chain phase. Do not retry from an error string alone. ## Classify the phase | Phase | Evidence | Next action | | ------------------------------- | ------------------------------------------ | -------------------------------------------- | | Not submitted | No transaction identifier | Correct locally and rebuild | | Submitted, status unknown | Transaction identifier, no terminal status | Query transaction and record state | | Rejected swap | Terminal rejection, no pending output | Requote and use a confirmed unspent record | | Accepted swap | Accepted transaction and `swap_id` | Read pending output and claim, do not reswap | | Submitted claim, status unknown | Claim transaction identifier | Query claim and mapping state | | Rejected claim | Pending output still exists | Correct claim inputs and retry | | Accepted claim | Pending output removed | Discover and store token records | If submission status is unknown, keep the input record reserved until its commitment state and transaction outcome are confirmed. ## Pre-submit failures These should be caught before proving or broadcasting: ### No sufficient token record The AMM consumes one input record. Acquire a larger record through the token program or select a different amount. Do not attempt to pass several records. ### Wrong token record Compare the record's concrete token program with canonical pool token order and direction. Symbols and API metadata are not sufficient. ### Base-unit amount is invalid Parse the user's decimal input into an exact integer using the token metadata decimals. Reject a fractional base unit or a value outside `u128`. ### Invalid price limit Refresh the slot and require a limit strictly below current price for `zero_for_one` or strictly above it for `one_for_zero`. A limit equal to current price is invalid. ### Economically empty dust trade If fee flooring reduces effective input to zero, the trade produces no output and returns the input. Raise the amount or decline the order. ## Swap rejection Common finalize rejection causes include: | Cause | Diagnostic | Recovery | | --------------------------- | -------------------------------------------- | -------------------------------------------------------------- | | Deadline expired | Current height exceeds request deadline | Read a fresh height, requote, and sign a new request | | Pause or disabled pool | Public control mapping or pool flag changed | Wait, choose another active route, or follow operator guidance | | Token mismatch | Supplied token IDs differ from pool state | Rebuild from canonical pool data | | Price limit out of range | Limit outside global constants | Clamp only according to user policy and requote | | Price direction wrong | Limit is not strict relative to current slot | Refresh state and recompute | | Amount zero | Public input is zero | Use a positive economically meaningful amount | | Minimum output not met | Final raw output is below floor | Refresh quote, change amount or tolerance, or cancel | | Confidential address reused | Address already marked used | Derive fresh blinding material | | Token-chain mismatch | Multi-hop input or output IDs do not connect | Rebuild the route by concrete token ID | | Arithmetic boundary | Helper precondition or integer fit fails | Reduce scope and investigate before retrying | A rejected order should not create a usable pending output. Before reusing its input record, confirm rejection and record spend state with chain data. Client timeouts are not proof of rejection. ## Accepted partial execution An accepted swap can leave input unspent while still meeting `amount_out_min`. The claim returns that remainder in a token record. Possible causes include: * Price limit reached * Five-iteration single-hop cap reached * Three-iteration per-hop multi-hop cap reached * Zero effective input after fee flooring Read `swap_outputs` and show the original-input remainder. Do not automatically submit another swap for it. The user should receive the refund record, review current state, and authorize any follow-up order. ## Accepted swap with no claim If the swap is accepted, recovery is a claim, not a repeated swap. 1. Extract or reconstruct `swap_id` from the accepted transition output. 2. Read `swap_outputs[swap_id]`. 3. Recover the original signer and private blinding factor. 4. Submit `claim_swap_output` with exact mapping values and current signer freezelist proofs. 5. Confirm mapping removal. 6. Decrypt and store returned token records. Trading pauses do not directly block claim finalizers. Diagnose a failed claim from the pending mapping and token-transfer result. ## Claim rejection ### Confidential address mismatch Use the same signer and factor that created the confidential address. A new factor cannot be substituted after the swap. ### Mapping value mismatch Read the mapping again and copy every token and amount exactly. Do not use quoted output or a rounded display amount. ### Wrong router claim Both core swap paths use `claim_swap_output`. If an output or refund is wrapped, select the matching `shield_swap_router.aleo` claim adapter from the deployment asset registry. ### Output already claimed If the mapping is absent, inspect the prior claim transaction and local record scanner. Repeating the claim cannot recreate the removed entry. ### Token transfer failure Confirm the concrete token programs, amounts, deployment availability, and record output handling. The AMM mapping may remain present after a rejected claim, allowing a corrected retry. ## Lost blinding recovery material The normal claim path requires the original signer and private factor. The protocol does not provide an administrator recovery or redirect function for pending swap outputs. Wallets should persist encrypted recovery material before swap submission and include it in backup procedures. Investigator-owned compliance records support authorized attribution but are not spend credentials. ## Missing output records If the claim is accepted but the wallet shows no funds: 1. Confirm the pending mapping was removed. 2. Retrieve the accepted claim transaction outputs. 3. Enumerate record, dynamic-record, and dynamic-ID record outputs. 4. Decrypt with the signer's view key. 5. Preserve `_version` and `_nonce` when parsing. 6. Match each record to its concrete token program. 7. Rebuild the local record index without rebroadcasting the claim. Verify confidential settlement from accepted claim outputs and record decryption. Public balance changes do not show record delivery. ## Multi-hop-specific recovery * A route rejection is atomic. Do not assume earlier hops produced claimable intermediate assets. * An accepted route returns final output and can return remaining original input. * If a hop hit its iteration cap, a follow-up route begins from new public pool state and needs a new input record after the refund claim. * A two-hop request still carries a padded third hop. Validate `hop_count` before interpreting route telemetry. * Final minimum output applies to the route output, not to the original-input remainder. ## Operational metadata failures An off-chain token API outage can prevent a frontend from discovering symbols or constructing operator onboarding steps. It does not change an existing pool's public token identifiers. The API seed script is separate from on-chain pool-creation allowlisting. After a metadata failure, confirm the environment, run a dry run, review each token program, and authorize on-chain actions separately. ## Incident record For every material failure, retain: * Network, program ID, and edition * Pool and route identifiers * Transaction identifiers and terminal status * Block heights used for quote and deadline * Public request parameters * Slot and relevant tick snapshots * Local record handles, never plaintext in general logs * Pending-output snapshot * Client and SDK version * Recovery action and result When identity disclosure is required, use the approved compliance-record process. Do not mix decrypted investigator material into ordinary support logs. Return to [Trader workflow](./trader-workflow) after the order reaches a known terminal state.