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

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.