Diagnosing Unexpected Vyper Reverts from Missing Custom Error Definitions

Unexpected revert due to missing or mismatched custom error definition

The transaction aborts with a generic revert message instead of the intended custom error. This happens when a `revert` statement references an error selector that has no matching `error` declaration in the contract, causing the compiler to fall back to a generic revert. The result is a loss of diagnostic information for the user and a difficult debugging experience.

Diagnostic table

Condition	Likely cause	Symptom
Revert without custom error	No `error` declaration or mismatched selector	Generic "revert" error, no reason
Selector mismatch	Error defined but `revert` uses wrong selector	Transaction fails, error data does not match any defined error
Compiler version < 0.3.0	Custom error syntax unsupported	Syntax error at compile time
Revert with generic revert but no errorData	No custom error defined or selector not generated	Transaction fails with generic revert, no error identifier in receipt

Concrete example

Consider the following snippet:

error InsufficientBalance(uint256 requested, uint256 available);
...
revert InsufficientBalance(requested, available);

The compiler computes the selector as the lower four bytes of keccak256('InsufficientBalance(uint256,uint256)'). If the `revert` line uses a different selector—perhaps because the argument types were changed without recompiling—the transaction will abort with a generic revert, and the user sees no useful diagnostic.

Step‑by‑step checks

1. Compile the contract with Vyper ≥0.3.0. The compiler must succeed and report no errors on the custom error definition. Verify the output contains a line similar to “Generated selector for InsufficientBalance: 0xab”.
2. Run a static analysis tool such as `vyper-check` or an IDE linter. It should flag any `revert` that cites an undefined selector. If the tool reports “unknown error InsufficientBalance”, the selector is missing.
3. Deploy the compiled bytecode to a testnet or a local Hardhat node. Ensure the deployment transaction succeeds.
4. Invoke a transaction that triggers the `revert`. Examine the transaction receipt; the `errorData` field must show the expected 4‑byte selector (e.g., 0xab).
5. If the receipt shows a generic revert, repeat the compile step and confirm the selector generation. Check that the error definition and the `revert` statement use identical argument types and that the selector matches the one shown in the receipt.

Verification checklist

• Compiler output includes a selector line for each custom error. No compilation warnings about unknown errors.
• Linter reports zero findings related to undefined selectors in `revert` statements.
• Deployed bytecode contains the selector bytes for the custom error when inspected with a tool such as `etherscan` or `web3.py`.
• Transaction receipt shows the correct selector in the `errorData` field, not a generic revert code.

Fixes tied to findings

• Define the custom error with the exact syntax `error InsufficientBalance(uint256 requested, uint256 available);` and ensure the `revert` statement uses the same error name and argument order, including exact spelling and case.
• After any change to the error’s argument types, re‑compile the contract. The selector is derived from the name and the types, so a mismatch will cause a selector mismatch.
• Update the `revert` line to `revert InsufficientBalance(requested, available);` or keep the error definition unchanged and let Vyper insert the correct selector automatically.
• If you need a deterministic selector, you can prepend the `error` definition with a comment indicating the expected selector, but Vyper still generates it automatically; manual overrides are not supported.

Escalation criteria

If after completing the compile, lint, and test‑net verification the transaction still reverts with a generic message, perform the following checks:

• Confirm the selector displayed in the receipt matches the one generated for the defined error. You can obtain the expected selector by running `vyperc ` and looking for the “selector” line.
• Ensure there are no duplicate error names in the contract; duplicate names can cause the compiler to generate different selectors for the same logical error.
• Verify the Vyper compiler version is recent enough. Custom error support was introduced in version 0.3.0; older releases will reject the `error` keyword.
• Inspect the bytecode for the presence of the selector bytes. A missing selector indicates a compilation issue or an incorrect `revert` expression.
• Make sure the transaction that triggers the revert calls the correct function and that no surrounding `try/except` block catches the revert and hides the error.

When all these diagnostics pass and the problem persists, consider reporting the case to the Vyper development team, attaching the contract source, the exact compiler version, and the transaction payload that triggers the unexpected revert.