> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/circlefin/evm-cctp-contracts/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions when working with EVM CCTP Contracts

## Deployment Issues

### Docker on M1 Chips

<Warning>
  Some machines, including those with M1 chips, may be unable to build the Docker image locally. This is a known issue.
</Warning>

**Workaround options:**

1. **Use native Foundry installation**: Instead of Docker, install Foundry directly using the official installation script:
   ```bash theme={null}
   curl -L https://foundry.paradigm.xyz | bash
   foundryup
   ```

2. **Use Rosetta**: Run Docker with Rosetta 2 emulation:
   ```bash theme={null}
   docker run --platform linux/amd64 --rm foundry "<COMMAND>"
   ```

3. **Build on different architecture**: Build the Docker image on an x86\_64 machine and push to a registry.

### Environment Configuration

If deployment scripts fail, verify all required environment variables are set:

<Accordion title="V1 Required Variables">
  ```bash theme={null}
  MESSAGE_TRANSMITTER_DEPLOYER_KEY
  TOKEN_MESSENGER_DEPLOYER_KEY
  TOKEN_MINTER_DEPLOYER_KEY
  TOKEN_CONTROLLER_DEPLOYER_KEY
  ATTESTER_ADDRESS
  USDC_CONTRACT_ADDRESS
  REMOTE_USDC_CONTRACT_ADDRESS
  MESSAGE_TRANSMITTER_PAUSER_ADDRESS
  TOKEN_MINTER_PAUSER_ADDRESS
  MESSAGE_TRANSMITTER_RESCUER_ADDRESS
  TOKEN_MESSENGER_RESCUER_ADDRESS
  TOKEN_MINTER_RESCUER_ADDRESS
  TOKEN_CONTROLLER_ADDRESS
  DOMAIN
  REMOTE_DOMAIN
  BURN_LIMIT_PER_MESSAGE
  ```
</Accordion>

<Accordion title="V2 Required Variables">
  For V2 deployments, see the [V2 deployment section](/v2/deployment) for a complete list of required environment variables.
</Accordion>

## Attestation Service Issues

### Rate Limiting

<Warning>
  The attestation service is rate-limited to **1 request per second**. Exceeding this limit will result in failed requests.
</Warning>

**Solution**: Implement proper rate limiting in your application:

```javascript theme={null}
let attestationResponse = {status: 'pending'};
while(attestationResponse.status != 'complete') {
    const response = await fetch(
        `https://iris-api-sandbox.circle.com/attestations/${messageHash}`
    );
    attestationResponse = await response.json();
    // Wait 2 seconds between requests
    await new Promise(r => setTimeout(r, 2000));
}
```

### Attestation Pending Too Long

If an attestation remains in `pending` status for an extended period:

1. **Verify the transaction was confirmed**: Check that your `depositForBurn` transaction was successfully mined
2. **Check the correct network**: Ensure you're querying the right attestation service (sandbox vs. production)
3. **Wait for finality**: Attestations require block finality, which varies by chain
4. **Verify message hash**: Ensure the message hash was correctly extracted from transaction logs

```javascript theme={null}
const eventTopic = web3.utils.keccak256('MessageSent(bytes)');
const log = transactionReceipt.logs.find((l) => l.topics[0] === eventTopic);
const messageBytes = web3.eth.abi.decodeParameters(['bytes'], log.data)[0];
const messageHash = web3.utils.keccak256(messageBytes);
```

## Transaction Issues

### Gas Estimation Failures

If gas estimation fails when calling CCTP functions:

<AccordionGroup>
  <Accordion title="Check token allowance">
    Ensure you've approved the TokenMessenger contract before calling `depositForBurn`:

    ```javascript theme={null}
    const approveTx = await usdcContract.methods
        .approve(TOKEN_MESSENGER_ADDRESS, amount)
        .send({gas: approveTxGas});
    ```
  </Accordion>

  <Accordion title="Verify sufficient balance">
    Confirm your address has enough USDC for the transfer amount plus fees.
  </Accordion>

  <Accordion title="Check contract pause status">
    The contract may be paused. Check the `paused` state:

    ```javascript theme={null}
    const isPaused = await messageTransmitter.methods.paused().call();
    if (isPaused) {
        console.log('Contract is paused');
    }
    ```
  </Accordion>

  <Accordion title="Validate parameters">
    Ensure all parameters meet requirements:

    * Amount > 0
    * Recipient address is not zero
    * Max fee \< amount
    * Min fee requirements met (V2)
  </Accordion>
</AccordionGroup>

### "Invalid Message Version" Error

This error occurs when message versions don't match:

* **V1 contracts**: Use message version 0
* **V2 contracts**: Use message version 1

Ensure you're interacting with the correct contract version and using compatible message formats.

### "Nonce Already Used" Error

This error means the message has already been processed on the destination chain.

**Causes:**

* Message was already received and processed
* Duplicate transaction submission

**Solution**: This is expected behavior for replay protection. Each message can only be processed once.

## Testing and Debugging

### Running Tests with Debug Logs

Use Foundry's verbosity flags to see detailed test output:

```bash theme={null}
# Basic test output
forge test

# Show console.log() statements
forge test -vv

# Show stack traces for failures
forge test -vvv

# Show all traces including passing tests
forge test -vvvv

# Show all traces and setup
forge test -vvvvv
```

<Note>
  Contracts must import `lib/forge-std/src/console.sol` to use `console.log()` statements.
</Note>

### Static Analysis

Run Mythril for security analysis:

```bash theme={null}
# Analyze specific component
make analyze-message-transmitter
make analyze-message-transmitter-v2
make analyze-token-messenger-minter

# Or analyze a specific file
myth -v4 analyze $FILE_PATH --solc-json mythril.config.json --solv 0.7.6
```

<Warning>
  Mythril analysis can take several minutes to complete.
</Warning>

## Common Error Messages

<AccordionGroup>
  <Accordion title="'Amount must be nonzero'">
    You're attempting to burn 0 tokens. Ensure the amount is greater than 0.
  </Accordion>

  <Accordion title="'Mint recipient must be nonzero'">
    The recipient address is set to zero. Provide a valid destination address.
  </Accordion>

  <Accordion title="'Max fee must be less than amount'">
    The max fee equals or exceeds the transfer amount. Reduce the max fee.
  </Accordion>

  <Accordion title="'Insufficient max fee' (V2)">
    The max fee is below the minimum required fee. Calculate minimum fee:

    ```javascript theme={null}
    const minFee = await tokenMessenger.methods.getMinFeeAmount(amount).call();
    ```
  </Accordion>

  <Accordion title="'Pausable: paused'">
    Contract operations are paused. Wait for the contract to be unpaused by the pauser role.
  </Accordion>

  <Accordion title="'Invalid destination domain'">
    The destination domain is not configured. Verify the domain ID and ensure remote token messenger is registered.
  </Accordion>

  <Accordion title="'Denylistable: account is on denylist' (V2)">
    Your address (msg.sender or tx.origin) is on the denylist. Contact support if you believe this is an error.
  </Accordion>

  <Accordion title="'Signature threshold exceeds attesters'">
    The signature threshold is set higher than the number of enabled attesters. This is a configuration error during initialization.
  </Accordion>
</AccordionGroup>

## Integration Testing

### Running Anvil Tests

Test your integration locally with Anvil:

```bash theme={null}
# Start Anvil testnet and run integration tests
make anvil-test
```

Example integration tests are available in the `anvil/` directory.

### Linting

Run Solhint to catch common issues:

```bash theme={null}
yarn lint
```

## Need More Help?

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-question" href="/resources/faq">
    Frequently asked questions
  </Card>

  <Card title="Security" icon="shield-halved" href="/resources/security">
    Report security vulnerabilities
  </Card>
</CardGroup>