Purpose

This is a short guide for debugging the custom program errors that come up when interacting with your anchor program using the javascript client library.

Steps

1. Identify the hexadecimal value for the program error
2. Convert the hexadecimal to an integer.
3. If the value is between 100 and 300, the error is coming from anchor. You can determine the error by looking at the anchor source code.
4. If the value is greater than 300, the error is coming from your solana program. Your program idl (located in your {anchor_workspace}/target/idl directory) contains your program's errors and corresponding numeric codes.

Anchor Error Example

Transaction simulation failed: Error processing Instruction 1: custom program error: 0xa3 
    Program 11111111111111111111111111111111 invoke [1]
    Program 11111111111111111111111111111111 success
    Program 8ssSFKfX285ynByKAQNMSUHMGbDzQjV9JTz37MRgnBwh invoke [1]
    Program log: Custom program error: 0xa3
    Program 8ssSFKfX285ynByKAQNMSUHMGbDzQjV9JTz37MRgnBwh consumed 4295 of 200000 compute units
    Program 8ssSFKfX285ynByKAQNMSUHMGbDzQjV9JTz37MRgnBwh failed: custom program error: 0xa3
Translating error Error: failed to send transaction: Transaction simulation failed: Error processing Instruction 1: custom program error: 0xa

1. Identify that the hexadecimal value is 0xa3
2. Convert 0xa3 to 163
3. Look up 163 in anchor source code. See it's an AccountDidNotDeserialize error and continue debugging from there (in this case my solana program cli library has a stale idl)

Program Example

Transaction simulation failed: Error processing Instruction 0: custom program error: 0x133 
    Program Bxvjc7hGds9PajMiX8TCsyGnwWqP49qCYJDSQ3VonFeE invoke [1]
    Program log: Custom program error: 0x133
    Program Bxvjc7hGds9PajMiX8TCsyGnwWqP49qCYJDSQ3VonFeE consumed 26278 of 200000 compute units
    Program Bxvjc7hGds9PajMiX8TCsyGnwWqP49qCYJDSQ3VonFeE failed: custom program error: 0x133

1. Identify that the hexadecimal value is 0x133
2. Convert 0x133 to 307
3. Look up 307 in my program's idl file. IDL file looks like:

"errors": [
    {
      "code": 300,
      "name": "InvalidAMMAuthority",
      "msg": "Clearing house not AMM authority"
    },
...
    {
      "code": 307,
      "name": "InsufficientCollateral",
      "msg": "Insufficient collateral"
    },
...
  ],

4. See that the error is InsufficientCollateral and continue debugging.