Errors & Logs Best Practices
Balance observability with CU discipline: stable error codes for clients, gated logs for engineers, structured events for indexers.
How to Use This List
- Publish IDL/errors.json on every release.
- Simulate top failure paths in CI.
- Feature-gate verbose logs.
A - Errors
- Return
ProgramError- never panic on user-controlled input. Clean failure codes. - Keep custom error codes stable; append new variants only. Client compatibility.
- Publish machine-readable error tables with program version. Decode accuracy.
- Map CPI errors deliberately when UX needs program-specific messaging. Clear accountability.
- Unit test every error branch. Coverage for failure modes.
B - Logs
- Gate
msg!behind features in release builds. CU control. - Never log secrets, seeds, or private user data. Public chain.
- Use prefixed log tokens for grep (
MYAPP:step). Ops efficiency. - Avoid logs inside loops and CPI chains. CU multiplication.
- Prefer events for indexer-bound observability. Structured pipelines.
C - Operations
- Simulate before send in dApps; show decoded errors. UX + support savings.
- Archive IDL + error JSON per deploy hash. Incident time travel.
- Add LiteSVM tests asserting specific error codes. Regression safety.
- Document debug playbook for support team. Faster resolution.
- Strip temporary debug logs before mainnet tag. Cost and noise.
FAQs
Errors vs events?
Errors fail; events observe success paths mainly.
Anchor enough?
Still gate logs and publish IDL.
Pinocchio logs?
Same syscall costs.
i18n?
Off-chain map codes.
Monitoring?
Index events not raw spam logs.
CU budget?
Logs affect landing on tight ix.
Immutable program?
Error table frozen - plan codes.
Surfpool?
Debug default.
Kit 7.0.0?
Client decode standard.
Security?
Errors can leak hints - generic user text.
Compliance?
No PII in logs.
CI?
Fail on new panic paths.
Related
- Error Handling Basics - Intro
- Logging with msg! - CU-aware logs
- Error Code & require! - Anchor stack
Stack versions: This page was written for Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0, and LiteSVM 0.6.x.