Error Codes & Handling

Relevant source files

The following files were used as context for generating this wiki page:

• src/provider.ts
• src/types.ts
• src/constants.ts
• src/connector.ts
• test/provider.spec.ts

The Walletless provider implements a robust error handling system designed to comply with the EIP-1193 standard. It ensures that both internal logic errors and RPC-level failures are caught, formatted, and returned to the consuming application in a predictable manner. This system is critical for E2E testing, as it allows developers to simulate "User Rejected" scenarios and handle network-level failures deterministically.

Errors in Walletless are categorized into three primary types:

1. Provider Errors: Standardized EIP-1193 errors for user interactions (e.g., rejecting a transaction).
2. RPC Errors: Errors returned by the underlying Anvil RPC node during read or write operations.
3. Validation Errors: Internal logic errors, such as providing an invalid account index or switching to an unsupported chain.

Sources: src/types.ts:160-174, src/provider.ts:252-300

EIP-1193 Provider Errors

The library defines a specific ProviderRpcError class that extends the native JavaScript Error class. This class is used to wrap errors with specific numeric codes and optional metadata, facilitating compliance with Ethereum provider standards.

ProviderRpcError Structure

Field	Type	Description
code	number	The error code identifying the type of error.
message	string	A human-readable description of the error.
data	unknown	(Optional) Additional technical details or error context.

Sources: src/types.ts:161-174

Standard Error Codes

The ProviderErrorCode constant maps common EIP-1193 error scenarios to their required numeric values.

Constant	Code	Scenario
UserRejectedRequest	4001	User declined a transaction or signature request.
Unauthorized	4100	The provider is not authorized for the requested action.
UnsupportedMethod	4200	The requested RPC method is not supported by the provider.
Disconnected	4900	The provider is disconnected from all chains.
ChainDisconnected	4901	The provider is disconnected from the specific chain.

Sources: src/types.ts:179-185

Simulated Error Handling

A core feature of Walletless is the ability to programmatically trigger errors to test DApp resilience. This is achieved through internal state flags that intercept write operations.

This diagram illustrates how the request handler checks internal flags before processing signing or transaction methods.
Sources: src/provider.ts:252-273

Rejection Control

Users can toggle these error states using the setRejectSignature and setRejectTransaction methods. When rejectTransaction is set to true, any eth_sendTransaction call will immediately throw a ProviderRpcError with code 4001. Similarly, personal_sign, eth_sign, and eth_signTypedData methods check the rejectSignature flag.

Sources: src/provider.ts:252-273, test/provider.spec.ts:517-540

RPC Error Propagation

When Walletless acts as a "Man-in-the-Middle," it must handle errors returned by the upstream RPC URL. This occurs during handleReadMethod calls or when forwarding raw transactions.

RPC Response Handling

The sendJsonRpc function parses the JSON response from the Anvil node. If the error field is present in the JSON-RPC response, Walletless extracts the message and code to throw a local error.

if (data.error) {
    const error = new Error(data.error.message);
    // @ts-expect-error - Adding code property to error
    error.code = data.error.code;
    throw error;
}

Sources: src/provider.ts:232-240

Configuration & Validation Errors

The provider performs several synchronous checks to prevent invalid states during testing. These errors are typically standard JavaScript Error objects rather than ProviderRpcError instances.

Chain Validation

When switching chains via wallet_switchEthereumChain or the setChain helper, the provider verifies if the target chainId exists in the supportedChainIds array defined during initialization. If the chain is missing, it throws an error with code 4902.

Account Resolution Errors

The resolveAccount utility throws descriptive errors when it cannot map a SigningAccountInput to a valid account.

• Invalid Index: Thrown if a number outside 0-9 is provided for Anvil accounts.
• Unknown Address: Thrown if a 42-character string is provided that does not match one of the default ANVIL_ACCOUNTS.
• Invalid Format: Thrown if the input doesn't meet the requirements for an index, address, private key, or viem Account object.

Sources: src/provider.ts:54-94

Summary of Handled Scenarios

Scenario	Error Type	Source	Result
Invalid RPC Method	UnsupportedMethod	handleWriteMethod	Throws "Unsupported write method"
Chain Not Found	Code 4902	handleWalletMethod	Throws "Chain X is not supported"
Manual Disconnect	Code 4900	disconnect()	Emits disconnect event
Anvil Node Down	Fetch Error	sendJsonRpc	Throws native network error
Anvil Logic Error	RPC Error	sendJsonRpc	Throws error with RPC code/message

Sources: src/provider.ts:232-240, 317, 392, 575, src/types.ts:179-185

The error handling logic in Walletless ensures that E2E tests can accurately simulate and respond to the wide variety of failure modes present in a live Web3 environment. By combining standardized EIP-1193 codes with configurable rejection states, it provides a high-fidelity testing platform for DApp developers.