A custom error is a structured way for a Solidity smart contract to report why an operation reverted. It can include typed data, such as a required balance or the relevant account. A custom error helps developers and applications interpret a failed call, but it is not proof that the website explaining the error is accurate.
Tricia tries to reserve a fictional science kit and the application rejects her request. Instead of showing Something went wrong, the system identifies that the kit is already booked. Alicia can understand the immediate problem, while Kai Kai checks whether the message actually came from the intended contract.
This educational article is for parents, children and adult beginners. The school example is fictional and requires no cryptocurrency purchase, live wallet or student personal information.
The answer in one minute
A custom error is a structured way for a Solidity smart contract to report why an operation reverted. It can include typed data, such as a required balance or the relevant account. A custom error helps developers and applications interpret a failed call, but it is not proof that the website explaining the error is accurate.
A school example
Tricia tries to reserve a fictional science kit and the application rejects her request. Instead of showing Something went wrong, the system identifies that the kit is already booked. Alicia can understand the immediate problem, while Kai Kai checks whether the message actually came from the intended contract.
1. Failure should have a specific meaning
A smart contract may reject an action because the caller lacks authority, the state changed or a condition is unmet. A structured error can communicate which condition failed under the execution path.
2. Custom errors are defined in contract code
Solidity supports error declarations and revert statements that carry encoded error information. Tools can decode this information using the relevant ABI. The precise bytes and types matter.
3. A revert is not the same as a pending transaction
A transaction may be waiting for inclusion, included with unsuccessful execution or rejected before submission. An error from a simulated call is not proof that an actual transaction has been accepted and reverted.
4. Error names are developer-defined
An error called InsufficientApproval does not prove that the developer’s underlying approval policy is fair or correct. It is a label chosen by code authors, interpreted in the context of that implementation.
5. Errors can include useful arguments
A custom error may carry an address, amount or other typed value that helps explain a failed condition. Interfaces should avoid revealing unnecessary sensitive information and should not expose children’s real records in public transactions.
6. Decoding needs the right ABI and contract context
A wallet or explorer may display decoded revert data. The reader should check the network, contract address, current implementation and whether the tool’s ABI matches the code.
7. Simulation and execution can disagree
A simulated request may succeed at one state and fail later when another user books the last kit. A predicted error or success is conditional on the simulation assumptions.
8. The family activity: clear versus vague errors
Give children two slips: Request Failed and Kit Already Reserved. Ask which helps them respond responsibly. Then deliberately supply a false explanation and discuss why error text must be supported by evidence.
9. What a parent should check
Did the request reach the network? Was it included? Did it execute successfully? What current state does the authoritative application show? These questions are more useful than repeatedly pressing Submit.
How to check the evidence
Ask what the code is meant to establish, who has authority, what current state the result refers to, what assumptions were made and which real-world facts remain unverified. A valid digital record is not a guarantee that every external statement is true.
A parent-and-child exercise
Use the paper activity in this chapter. Run the normal case, then introduce a mistake, missing approval or outdated record. Ask the learner which conclusion remains justified and what evidence would resolve the problem. Paper analogies do not implement cryptographic security.
When a simpler system is enough
A school may meet its requirements using a conventional database, signed records, established access controls and an audit trail. Blockchain adds value only when a specific shared verification or governance need justifies the additional complexity.
Frequently asked questions
Does this guarantee the physical-world claim is true?
No. The mechanism establishes a defined technical result under its assumptions. External events and institutional decisions need appropriate evidence.
Can children learn this without investing?
Yes. Fictional examples and paper exercises are sufficient. No money, private keys or real accounts are needed.
Does every blockchain implement this the same way?
No. The relevant contract language, platform and governance design matter. Ethereum-specific mechanisms should not be applied indiscriminately to every blockchain.
Continue through the learning library
Read the related practical chapter, the English learning guide, the Simplified Chinese learning guide and the Master Blockchain hub.
Sources and limits
Technical reference: https://docs.soliditylang.org/en/latest/contracts.html#errors-and-the-revert-statement. General blockchain foundation: NIST IR 8202. The school scenarios are fictional and do not describe an actual eduKateSG blockchain deployment.