@solana/errors 6.3.1 → 6.3.2-canary-20260313112147

package/src/error.ts

@@ -0,0 +1,148 @@
+import { SolanaErrorCode, SolanaErrorCodeWithCause, SolanaErrorCodeWithDeprecatedCause } from './codes';
+import { SolanaErrorContext } from './context';
+import { getErrorMessage } from './message-formatter';
+
+/**
+ * A variant of {@link SolanaError} where the `cause` property is deprecated.
+ *
+ * This type is returned by {@link isSolanaError} when checking for error codes in
+ * {@link SolanaErrorCodeWithDeprecatedCause}. Accessing `cause` on these errors will show
+ * a deprecation warning in IDEs that support JSDoc `@deprecated` tags.
+ */
+export interface SolanaErrorWithDeprecatedCause<
+    TErrorCode extends SolanaErrorCodeWithDeprecatedCause = SolanaErrorCodeWithDeprecatedCause,
+> extends Omit<SolanaError<TErrorCode>, 'cause'> {
+    /**
+     * @deprecated The `cause` property is deprecated for this error code.
+     * Use the error's `context` property instead to access relevant error information.
+     */
+    readonly cause?: unknown;
+}
+
+/**
+ * A type guard that returns `true` if the input is a {@link SolanaError}, optionally with a
+ * particular error code.
+ *
+ * When the `code` argument is supplied and the input is a {@link SolanaError}, TypeScript will
+ * refine the error's {@link SolanaError#context | `context`} property to the type associated with
+ * that error code. You can use that context to render useful error messages, or to make
+ * context-aware decisions that help your application to recover from the error.
+ *
+ * @example
+ * ```ts
+ * import {
+ *     SOLANA_ERROR__TRANSACTION__MISSING_SIGNATURE,
+ *     SOLANA_ERROR__TRANSACTION__FEE_PAYER_SIGNATURE_MISSING,
+ *     isSolanaError,
+ * } from '@solana/errors';
+ * import { assertIsFullySignedTransaction, getSignatureFromTransaction } from '@solana/transactions';
+ *
+ * try {
+ *     const transactionSignature = getSignatureFromTransaction(tx);
+ *     assertIsFullySignedTransaction(tx);
+ *     /* ... *\/
+ * } catch (e) {
+ *     if (isSolanaError(e, SOLANA_ERROR__TRANSACTION__SIGNATURES_MISSING)) {
+ *         displayError(
+ *             "We can't send this transaction without signatures for these addresses:\n- %s",
+ *             // The type of the `context` object is now refined to contain `addresses`.
+ *             e.context.addresses.join('\n- '),
+ *         );
+ *         return;
+ *     } else if (isSolanaError(e, SOLANA_ERROR__TRANSACTION__FEE_PAYER_SIGNATURE_MISSING)) {
+ *         if (!tx.feePayer) {
+ *             displayError('Choose a fee payer for this transaction before sending it');
+ *         } else {
+ *             displayError('The fee payer still needs to sign for this transaction');
+ *         }
+ *         return;
+ *     }
+ *     throw e;
+ * }
+ * ```
+ */
+export function isSolanaError<TErrorCode extends SolanaErrorCodeWithDeprecatedCause>(
+    e: unknown,
+    code: TErrorCode,
+): e is SolanaErrorWithDeprecatedCause<TErrorCode>;
+export function isSolanaError<TErrorCode extends SolanaErrorCode>(
+    e: unknown,
+    code?: TErrorCode,
+): e is SolanaError<TErrorCode>;
+export function isSolanaError<TErrorCode extends SolanaErrorCode>(
+    e: unknown,
+    /**
+     * When supplied, this function will require that the input is a {@link SolanaError} _and_ that
+     * its error code is exactly this value.
+     */
+    code?: TErrorCode,
+): e is SolanaError<TErrorCode> {
+    const isSolanaError = e instanceof Error && e.name === 'SolanaError';
+    if (isSolanaError) {
+        if (code !== undefined) {
+            return (e as SolanaError<TErrorCode>).context.__code === code;
+        }
+        return true;
+    }
+    return false;
+}
+
+type SolanaErrorCodedContext = {
+    [P in SolanaErrorCode]: Readonly<{
+        __code: P;
+    }> &
+        (SolanaErrorContext[P] extends undefined ? object : SolanaErrorContext[P]);
+};
+
+/**
+ * Encapsulates an error's stacktrace, a Solana-specific numeric code that indicates what went
+ * wrong, and optional context if the type of error indicated by the code supports it.
+ */
+export class SolanaError<TErrorCode extends SolanaErrorCode = SolanaErrorCode> extends Error {
+    /**
+     * Indicates the root cause of this {@link SolanaError}, if any.
+     *
+     * For example, a transaction error might have an instruction error as its root cause. In this
+     * case, you will be able to access the instruction error on the transaction error as `cause`.
+     */
+    readonly cause?: TErrorCode extends SolanaErrorCodeWithCause ? SolanaError : unknown = this.cause;
+    /**
+     * Contains context that can assist in understanding or recovering from a {@link SolanaError}.
+     */
+    readonly context: SolanaErrorCodedContext[TErrorCode];
+    constructor(
+        ...[code, contextAndErrorOptions]: SolanaErrorContext[TErrorCode] extends undefined
+            ? [code: TErrorCode, errorOptions?: ErrorOptions | undefined]
+            : [code: TErrorCode, contextAndErrorOptions: SolanaErrorContext[TErrorCode] & (ErrorOptions | undefined)]
+    ) {
+        let context: SolanaErrorContext[TErrorCode] | undefined;
+        let errorOptions: ErrorOptions | undefined;
+        if (contextAndErrorOptions) {
+            Object.entries(Object.getOwnPropertyDescriptors(contextAndErrorOptions)).forEach(([name, descriptor]) => {
+                // If the `ErrorOptions` type ever changes, update this code.
+                if (name === 'cause') {
+                    errorOptions = { cause: descriptor.value };
+                } else {
+                    if (context === undefined) {
+                        context = {
+                            __code: code,
+                        } as unknown as SolanaErrorContext[TErrorCode];
+                    }
+                    Object.defineProperty(context, name, descriptor);
+                }
+            });
+        }
+        const message = getErrorMessage(code, context);
+        super(message, errorOptions);
+        this.context = Object.freeze(
+            context === undefined
+                ? {
+                      __code: code,
+                  }
+                : context,
+        ) as SolanaErrorCodedContext[TErrorCode];
+        // This is necessary so that `isSolanaError()` can identify a `SolanaError` without having
+        // to import the class for use in an `instanceof` check.
+        this.name = 'SolanaError';
+    }
+}

package/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * This package brings together every error message across all Solana JavaScript modules.
+ *
+ * # Reading error messages
+ *
+ * ## In development mode
+ *
+ * When your bundler sets the constant `__DEV__` to `true`, every error message will be included in
+ * the bundle. As such, you will be able to read them in plain language wherever they appear.
+ *
+ * > [!WARNING]
+ * > The size of your JavaScript bundle will increase significantly with the inclusion of every
+ * > error message in development mode. Be sure to build your bundle with `__DEV__` set to `false`
+ * > when you go to production.
+ *
+ * ## In production mode
+ *
+ * When your bundler sets the constant `__DEV__` to `false`, error messages will be stripped from
+ * the bundle to save space. Only the error code will appear when an error is encountered. Follow
+ * the instructions in the error message to convert the error code back to the human-readable error
+ * message.
+ *
+ * For instance, to recover the error text for the error with code `123`:
+ *
+ * ```package-install
+ * npx @solana/errors decode -- 123
+ * ```
+ *
+ * > [!IMPORTANT]
+ * > The string representation of a {@link SolanaError} should not be shown to users. Developers
+ * > should use {@link isSolanaError} to distinguish the type of a thrown error, then show a custom,
+ * > localized error message appropriate for their application's audience. Custom error messages
+ * > should use the error's {@link SolanaError#context | `context`} if it would help the reader
+ * > understand what happened and/or what to do next.
+ *
+ * # Adding a new error
+ *
+ * 1. Add a new exported error code constant to `src/codes.ts`.
+ * 2. Add that new constant to the {@link SolanaErrorCode} union in `src/codes.ts`.
+ * 3. If you would like the new error to encapsulate context about the error itself (eg. the public
+ *    keys for which a transaction is missing signatures) define the shape of that context in
+ *    `src/context.ts`.
+ * 4. Add the error's message to `src/messages.ts`. Any context values that you defined above will
+ *    be interpolated into the message wherever you write `$key`, where `key` is the index of a
+ *    value in the context (eg. ``'Missing a signature for account `$address`'``).
+ * 5. Publish a new version of `@solana/errors`.
+ * 6. Bump the version of `@solana/errors` in the package from which the error is thrown.
+ *
+ * # Removing an error message
+ *
+ * -   Don't remove errors.
+ * -   Don't change the meaning of an error message.
+ * -   Don't change or reorder error codes.
+ * -   Don't change or remove members of an error's context.
+ *
+ * When an older client throws an error, we want to make sure that they can always decode the error.
+ * If you make any of the changes above, old clients will, by definition, not have received your
+ * changes. This could make the errors that they throw impossible to decode going forward.
+ *
+ * # Catching errors
+ *
+ * See {@link isSolanaError} for an example of how to handle a caught {@link SolanaError}.
+ *
+ * @packageDocumentation
+ */
+export * from './codes';
+export * from './error';
+export * from './instruction-error';
+export * from './json-rpc-error';
+export * from './simulation-errors';
+export * from './stack-trace';
+export * from './transaction-error';

package/src/instruction-error.ts

@@ -0,0 +1,96 @@
+import { SOLANA_ERROR__INSTRUCTION_ERROR__CUSTOM, SOLANA_ERROR__INSTRUCTION_ERROR__UNKNOWN } from './codes';
+import { SolanaError } from './error';
+import { getSolanaErrorFromRpcError } from './rpc-enum-errors';
+
+const ORDERED_ERROR_NAMES = [
+    // Keep synced with RPC source: https://github.com/anza-xyz/solana-sdk/blob/master/instruction-error/src/lib.rs
+    // If this list ever gets too large, consider implementing a compression strategy like this:
+    // https://gist.github.com/steveluscher/aaa7cbbb5433b1197983908a40860c47
+    'GenericError',
+    'InvalidArgument',
+    'InvalidInstructionData',
+    'InvalidAccountData',
+    'AccountDataTooSmall',
+    'InsufficientFunds',
+    'IncorrectProgramId',
+    'MissingRequiredSignature',
+    'AccountAlreadyInitialized',
+    'UninitializedAccount',
+    'UnbalancedInstruction',
+    'ModifiedProgramId',
+    'ExternalAccountLamportSpend',
+    'ExternalAccountDataModified',
+    'ReadonlyLamportChange',
+    'ReadonlyDataModified',
+    'DuplicateAccountIndex',
+    'ExecutableModified',
+    'RentEpochModified',
+    'NotEnoughAccountKeys',
+    'AccountDataSizeChanged',
+    'AccountNotExecutable',
+    'AccountBorrowFailed',
+    'AccountBorrowOutstanding',
+    'DuplicateAccountOutOfSync',
+    'Custom',
+    'InvalidError',
+    'ExecutableDataModified',
+    'ExecutableLamportChange',
+    'ExecutableAccountNotRentExempt',
+    'UnsupportedProgramId',
+    'CallDepth',
+    'MissingAccount',
+    'ReentrancyNotAllowed',
+    'MaxSeedLengthExceeded',
+    'InvalidSeeds',
+    'InvalidRealloc',
+    'ComputationalBudgetExceeded',
+    'PrivilegeEscalation',
+    'ProgramEnvironmentSetupFailure',
+    'ProgramFailedToComplete',
+    'ProgramFailedToCompile',
+    'Immutable',
+    'IncorrectAuthority',
+    'BorshIoError',
+    'AccountNotRentExempt',
+    'InvalidAccountOwner',
+    'ArithmeticOverflow',
+    'UnsupportedSysvar',
+    'IllegalOwner',
+    'MaxAccountsDataAllocationsExceeded',
+    'MaxAccountsExceeded',
+    'MaxInstructionTraceLengthExceeded',
+    'BuiltinProgramsMustConsumeComputeUnits',
+];
+
+export function getSolanaErrorFromInstructionError(
+    /**
+     * The index of the instruction inside the transaction.
+     */
+    index: bigint | number,
+    instructionError: string | { [key: string]: unknown },
+): SolanaError {
+    const numberIndex = Number(index);
+    return getSolanaErrorFromRpcError(
+        {
+            errorCodeBaseOffset: 4615001,
+            getErrorContext(errorCode, rpcErrorName, rpcErrorContext) {
+                if (errorCode === SOLANA_ERROR__INSTRUCTION_ERROR__UNKNOWN) {
+                    return {
+                        errorName: rpcErrorName,
+                        index: numberIndex,
+                        ...(rpcErrorContext !== undefined ? { instructionErrorContext: rpcErrorContext } : null),
+                    };
+                } else if (errorCode === SOLANA_ERROR__INSTRUCTION_ERROR__CUSTOM) {
+                    return {
+                        code: Number(rpcErrorContext as bigint | number),
+                        index: numberIndex,
+                    };
+                }
+                return { index: numberIndex };
+            },
+            orderedErrorNames: ORDERED_ERROR_NAMES,
+            rpcEnumError: instructionError,
+        },
+        getSolanaErrorFromInstructionError,
+    );
+}

package/src/json-rpc-error.ts

@@ -0,0 +1,162 @@
+import {
+    SOLANA_ERROR__JSON_RPC__INTERNAL_ERROR,
+    SOLANA_ERROR__JSON_RPC__INVALID_PARAMS,
+    SOLANA_ERROR__JSON_RPC__INVALID_REQUEST,
+    SOLANA_ERROR__JSON_RPC__METHOD_NOT_FOUND,
+    SOLANA_ERROR__JSON_RPC__PARSE_ERROR,
+    SOLANA_ERROR__JSON_RPC__SCAN_ERROR,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_CLEANED_UP,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_NOT_AVAILABLE,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_STATUS_NOT_AVAILABLE_YET,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_KEY_EXCLUDED_FROM_SECONDARY_INDEX,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_SLOT_SKIPPED,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SLOT_SKIPPED,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_TRANSACTION_PRECOMPILE_VERIFICATION_FAILURE,
+    SOLANA_ERROR__JSON_RPC__SERVER_ERROR_UNSUPPORTED_TRANSACTION_VERSION,
+    SOLANA_ERROR__MALFORMED_JSON_RPC_ERROR,
+    SolanaErrorCode,
+} from './codes';
+import { SolanaErrorContext } from './context';
+import { SolanaError } from './error';
+import { safeCaptureStackTrace } from './stack-trace';
+import { getSolanaErrorFromTransactionError } from './transaction-error';
+
+interface RpcErrorResponse {
+    code: bigint | number;
+    data?: unknown;
+    message: string;
+}
+
+type TransactionError = string | { [key: string]: unknown };
+
+/**
+ * Keep in sync with https://github.com/anza-xyz/agave/blob/master/rpc-client-types/src/response.rs
+ * @hidden
+ */
+export interface RpcSimulateTransactionResult {
+    accounts:
+        | ({
+              data:
+                  | string // LegacyBinary
+                  | {
+                        // Json
+                        parsed: unknown;
+                        program: string;
+                        space: bigint;
+                    }
+                  // Binary
+                  | [encodedBytes: string, encoding: 'base58' | 'base64' | 'base64+zstd' | 'binary' | 'jsonParsed'];
+              executable: boolean;
+              lamports: bigint;
+              owner: string;
+              rentEpoch: bigint;
+              space?: bigint;
+          } | null)[]
+        | null;
+    err: TransactionError | null;
+    // Enabled by `enable_cpi_recording`
+    innerInstructions?:
+        | {
+              index: number;
+              instructions: (
+                  | {
+                        // Compiled
+                        accounts: number[];
+                        data: string;
+                        programIdIndex: number;
+                        stackHeight?: number;
+                    }
+                  | {
+                        // Parsed
+                        parsed: unknown;
+                        program: string;
+                        programId: string;
+                        stackHeight?: number;
+                    }
+                  | {
+                        // PartiallyDecoded
+                        accounts: string[];
+                        data: string;
+                        programId: string;
+                        stackHeight?: number;
+                    }
+              )[];
+          }[]
+        | null;
+    loadedAccountsDataSize: number | null;
+    logs: string[] | null;
+    replacementBlockhash: string | null;
+    returnData: {
+        data: [string, 'base64'];
+        programId: string;
+    } | null;
+    unitsConsumed: bigint | null;
+}
+
+export function getSolanaErrorFromJsonRpcError(putativeErrorResponse: unknown): SolanaError {
+    let out: SolanaError;
+    if (isRpcErrorResponse(putativeErrorResponse)) {
+        const { code: rawCode, data, message } = putativeErrorResponse;
+        const code = Number(rawCode);
+        if (code === SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE) {
+            const { err, ...preflightErrorContext } = data as RpcSimulateTransactionResult;
+            const causeObject = err ? { cause: getSolanaErrorFromTransactionError(err) } : null;
+            out = new SolanaError(SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SEND_TRANSACTION_PREFLIGHT_FAILURE, {
+                ...preflightErrorContext,
+                ...causeObject,
+            });
+        } else {
+            let errorContext;
+            switch (code) {
+                case SOLANA_ERROR__JSON_RPC__INTERNAL_ERROR:
+                case SOLANA_ERROR__JSON_RPC__INVALID_PARAMS:
+                case SOLANA_ERROR__JSON_RPC__INVALID_REQUEST:
+                case SOLANA_ERROR__JSON_RPC__METHOD_NOT_FOUND:
+                case SOLANA_ERROR__JSON_RPC__PARSE_ERROR:
+                case SOLANA_ERROR__JSON_RPC__SCAN_ERROR:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_CLEANED_UP:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_NOT_AVAILABLE:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_BLOCK_STATUS_NOT_AVAILABLE_YET:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_KEY_EXCLUDED_FROM_SECONDARY_INDEX:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_LONG_TERM_STORAGE_SLOT_SKIPPED:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_SLOT_SKIPPED:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_TRANSACTION_PRECOMPILE_VERIFICATION_FAILURE:
+                case SOLANA_ERROR__JSON_RPC__SERVER_ERROR_UNSUPPORTED_TRANSACTION_VERSION:
+                    // The server supplies no structured data, but rather a pre-formatted message. Put
+                    // the server message in `context` so as not to completely lose the data. The long
+                    // term fix for this is to add data to the server responses and modify the
+                    // messages in `@solana/errors` to be actual format strings.
+                    errorContext = { __serverMessage: message };
+                    break;
+                default:
+                    if (typeof data === 'object' && !Array.isArray(data)) {
+                        errorContext = data;
+                    }
+            }
+            out = new SolanaError(code as SolanaErrorCode, errorContext as SolanaErrorContext[SolanaErrorCode]);
+        }
+    } else {
+        const message =
+            typeof putativeErrorResponse === 'object' &&
+            putativeErrorResponse !== null &&
+            'message' in putativeErrorResponse &&
+            typeof putativeErrorResponse.message === 'string'
+                ? putativeErrorResponse.message
+                : 'Malformed JSON-RPC error with no message attribute';
+        out = new SolanaError(SOLANA_ERROR__MALFORMED_JSON_RPC_ERROR, { error: putativeErrorResponse, message });
+    }
+    safeCaptureStackTrace(out, getSolanaErrorFromJsonRpcError);
+    return out;
+}
+
+function isRpcErrorResponse(value: unknown): value is RpcErrorResponse {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        'code' in value &&
+        'message' in value &&
+        (typeof value.code === 'number' || typeof value.code === 'bigint') &&
+        typeof value.message === 'string'
+    );
+}

package/src/message-formatter.ts

@@ -0,0 +1,115 @@
+import { SOLANA_ERROR__INSTRUCTION_ERROR__UNKNOWN, SolanaErrorCode } from './codes';
+import { encodeContextObject } from './context';
+import { SolanaErrorMessages } from './messages';
+
+const INSTRUCTION_ERROR_RANGE_SIZE = 1000;
+
+const enum StateType {
+    EscapeSequence,
+    Text,
+    Variable,
+}
+type State = Readonly<{
+    [START_INDEX]: number;
+    [TYPE]: StateType;
+}>;
+const START_INDEX = 'i';
+const TYPE = 't';
+
+export function getHumanReadableErrorMessage<TErrorCode extends SolanaErrorCode>(
+    code: TErrorCode,
+    context: object = {},
+): string {
+    const messageFormatString = SolanaErrorMessages[code];
+    if (messageFormatString.length === 0) {
+        return '';
+    }
+    let state: State;
+    function commitStateUpTo(endIndex?: number) {
+        if (state[TYPE] === StateType.Variable) {
+            const variableName = messageFormatString.slice(state[START_INDEX] + 1, endIndex);
+
+            fragments.push(
+                variableName in context
+                    ? // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+                      `${context[variableName as keyof typeof context]}`
+                    : `$${variableName}`,
+            );
+        } else if (state[TYPE] === StateType.Text) {
+            fragments.push(messageFormatString.slice(state[START_INDEX], endIndex));
+        }
+    }
+    const fragments: string[] = [];
+    messageFormatString.split('').forEach((char, ii) => {
+        if (ii === 0) {
+            state = {
+                [START_INDEX]: 0,
+                [TYPE]:
+                    messageFormatString[0] === '\\'
+                        ? StateType.EscapeSequence
+                        : messageFormatString[0] === '$'
+                          ? StateType.Variable
+                          : StateType.Text,
+            };
+            return;
+        }
+        let nextState;
+        switch (state[TYPE]) {
+            case StateType.EscapeSequence:
+                nextState = { [START_INDEX]: ii, [TYPE]: StateType.Text };
+                break;
+            case StateType.Text:
+                if (char === '\\') {
+                    nextState = { [START_INDEX]: ii, [TYPE]: StateType.EscapeSequence };
+                } else if (char === '$') {
+                    nextState = { [START_INDEX]: ii, [TYPE]: StateType.Variable };
+                }
+                break;
+            case StateType.Variable:
+                if (char === '\\') {
+                    nextState = { [START_INDEX]: ii, [TYPE]: StateType.EscapeSequence };
+                } else if (char === '$') {
+                    nextState = { [START_INDEX]: ii, [TYPE]: StateType.Variable };
+                } else if (!char.match(/\w/)) {
+                    nextState = { [START_INDEX]: ii, [TYPE]: StateType.Text };
+                }
+                break;
+        }
+        if (nextState) {
+            if (state !== nextState) {
+                commitStateUpTo(ii);
+            }
+            state = nextState;
+        }
+    });
+    commitStateUpTo();
+    let message = fragments.join('');
+    if (
+        code >= SOLANA_ERROR__INSTRUCTION_ERROR__UNKNOWN &&
+        code < SOLANA_ERROR__INSTRUCTION_ERROR__UNKNOWN + INSTRUCTION_ERROR_RANGE_SIZE &&
+        'index' in context
+    ) {
+        message += ` (instruction #${(context as { index: number }).index + 1})`;
+    }
+    return message;
+}
+
+export function getErrorMessage<TErrorCode extends SolanaErrorCode>(
+    code: TErrorCode,
+    context: Record<string, unknown> = {},
+): string {
+    if (__DEV__) {
+        return getHumanReadableErrorMessage(code, context);
+    } else {
+        let decodingAdviceMessage = `Solana error #${code}; Decode this error by running \`npx @solana/errors decode -- ${code}`;
+        if (Object.keys(context).length) {
+            /**
+             * DANGER: Be sure that the shell command is escaped in such a way that makes it
+             *         impossible for someone to craft malicious context values that would result in
+             *         an exploit against anyone who bindly copy/pastes it into their terminal.
+             */
+            decodingAdviceMessage += ` '${encodeContextObject(context)}'`;
+        }
+        return `${decodingAdviceMessage}\``;
+    }
+}