Busca en todas las páginas de la documentación
Errores, registros y eventos son la forma en que un programa de Solana se comunica cuando el estado por sí solo no es suficiente: falla con un código, deja un rastro humano o publica un registro estructurado para los indexadores. Asigna a cada canal un trabajo y el soporte se reduce, la CU se mantiene predecible y las dApps dejan de mostrar "Transacción fallida".
Conceptos básicos de manejo de errores es la entrada práctica; Enumeraciones de errores personalizadas, Registro con msg!, Emisión de eventos, Decodificación de errores fuera de la cadena y Depuración de transacciones fallidas se centran en cada mecanismo. Esta página es el mapa subyacente: cómo las piezas se componen desde el manejador hasta la notificación de la billetera.
logMessages del explorador y cualquier cosa que tu cliente mapee desde ProgramError::Custom. Diseña esas superficies a propósito o enviarás fallos opacos y desperdicio de CU.Un manejador de instrucciones de Solana es esencialmente una función que devuelve ProgramResult (Result<(), ProgramError>). El éxito confirma las mutaciones de cuenta para esa transacción; el fallo aborta todo y revierte esas mutaciones. No hay confirmación parcial de "campos de error" de la manera en que algunos servidores de aplicaciones escriben una fila de error y aún así tienen éxito. El fallo en sí mismo es la señal.
Ese diseño empuja la observabilidad a los metadatos alrededor de la ejecución, no a cuentas duraderas de "último error" (a menos que construyas dicho estado en rutas de éxito). Tres canales complementarios llenan el vacío:
| Canal | Consumidor principal | Semántica de fallo | Carga útil típica |
|---|---|---|---|
| Error | Runtime, billeteras, decodificadores de dApp | La instrucción falla; el estado se revierte | ProgramError incorporado o Custom(u32) |
Registro (msg!) | Ingenieros, exploradores, soporte | Visible para pasos ejecutados hasta el fallo | Línea(s) de texto libre |
| Evento | Indexadores, análisis, webhooks | Emitido en rutas que tienen éxito lo suficiente como para registrar; la ix fallida no deja estado de evento duradero | Estructura con forma Borsh/IDL en registros |
Manejador de instrucciones
|
+-- verificar invariantes ---- Err(Código personalizado) ----> fallar tx + registros hasta ahora
|
+-- msg!("paso=...") ---- Costo de CU -------------> logMessages
|
+-- emit!(Evento {..}) --- bytes estructurados ----> consumidores de IDL / indexadores
|
+-- Ok(()) -------------- confirmar escrituras de cuentaLos errores son el contrato de flujo de control. Prefiere códigos personalizados tipificados para reglas visibles para el usuario (InsufficientFunds, SlippageExceeded) y los incorporados para fallos genéricos de argumentos o forma de cuenta cuando realmente apliquen. Los registros son un canal de depuración y operaciones: cortos, prefijados, con control de características cuando sea posible. Los eventos son el canal estructurado para sistemas fuera de la cadena que no deberían analizar texto libre.
Los tres comparten una propiedad: los registros de transacciones son públicos. Trata los mensajes, las líneas de registro y los campos de eventos como datos de cartelera. Las semillas, las claves privadas, la PII y los detalles internos listos para exploits no pertenecen allí.
Rust en la cadena no devuelve errores de String al cliente de manera útil. Los clientes ven un ID de programa más un código de error (a menudo hexadecimal en exploradores: custom program error: 0x1770). Tu trabajo es hacer que ese número sea estable, documentado y decodificable.
Los programas nativos típicamente definen una enumeración #[repr(u32)] e implementan From en ProgramError::Custom. Anchor 0.32.1 usa enumeraciones #[error_code] que aterrizan en el IDL con nombres y cadenas opcionales #[msg("...")], convencionalmente compensadas a partir de 6000. De cualquier manera:
errors.json mantenido manualmente para nativos).u32 puede significar cosas diferentes en programas diferentes.Los detalles y patrones se encuentran en Enumeraciones de errores personalizadas y Conceptos básicos de manejo de errores. El punto explicativo: la enumeración es una superficie de API pública, tan importante como los discriminadores de instrucciones.
msg!: presupuesta los registros como código de ruta activasolana_program::msg! (y los envoltorios de Anchor) invocan la llamada al sistema de registro. El costo escala con las llamadas y el tamaño de la carga útil. En un presupuesto de CU ajustado, un bucle de registros formateados puede llevar una transacción a cómputo excedido y parecer misterioso hasta que leas la simulación.
Reglas prácticas:
cfg para que las compilaciones de mainnet permanezcan silenciosas.VAULT:deposit_ok) para que las operaciones puedan buscar sin arqueología.El registro brilla para validadores locales, rastreos de Surfpool, pruebas de LiteSVM y instrumentación de incidentes cortos. Es un sustituto a largo plazo pobre para errores tipificados (UX) o eventos (indexadores). Ver Registro con msg!.
Cuando los paneles, los motores de riesgo o los complementos de Geyser necesitan campos confiables, el análisis de msg! de texto libre se convierte en un pasivo. Anchor emit! / emit_cpi! y las convenciones nativas de sol_log_data colocan estructuras tipificadas en el flujo de registro con un esquema definido por IDL o documentación.
Los eventos aún cuestan CU y permanecen públicos. Mantén las cargas útiles pequeñas (claves públicas, montos, enumeraciones), versiona los diseños cuando los campos se rompan y trata el estado de la cuenta como autoritativo. Los eventos describen resultados para los consumidores; no son un segundo libro mayor. Las instrucciones fallidas no confirman el estado del programa, así que no confíes en "eventos de error" como verdad duradera. Decodifica códigos de error para la UX de fallos; usa eventos para resultados de dominio exitosos. Inmersión profunda: Emisión de eventos.
Custom(n) a lenguaje de productoLas billeteras a menudo muestran un fallo genérico. Tu dApp (o herramienta de soporte) debería hacerlo mejor:
simulateTransaction (o confirma y recupera meta) con las mismas cuentas y datos.errors de IDL (Anchor) o una tabla publicada (nativa) a través de ayudantes generados para @solana/kit 7.0.0 o tu propia búsqueda.Fija el artefacto decodificador al hash del programa desplegado. Los IDL obsoletos son una causa común de ruido de soporte de "nombre de error incorrecto". Patrones completos de cliente: Decodificación de errores fuera de la cadena.
Cuando una transacción se ejecuta y falla, los metadatos típicamente incluyen logMessages para el trabajo realizado hasta el error. Usa esa pila para ver qué programa se invocó, qué CPI estaba activa y qué código personalizado terminó la ejecución. Cuando una transacción nunca aterriza (hash de bloque, caída, tarifa insuficiente), obtienes una clase de problema diferente: ningún registro del programa porque el programa nunca se ejecutó.
Un bucle confiable:
Informe del usuario / fallo de CI
|
v
Simular mismo mensaje --> leer registros + err
|
v
Mapear código a través de IDL --> formular hipótesis
|
v
Reproducir en LiteSVM / Surfpool --> agregar prueba de regresión
|
v
Corregir (código, cuentas, CU o cliente) + eliminar registros temporalesCLI (solana confirm -v, APIs de simulación), exploradores, rastreos de Surfpool 0.12.0 y pruebas unitarias de LiteSVM consumen las mismas señales fundamentales: códigos y registros. Detalles del flujo de trabajo: Depuración de transacciones fallidas.
Usa un mapa compartido entre los equipos de programas y clientes:
| Pregunta | Canal | Herramienta en cadena | Herramienta fuera de cadena |
|---|---|---|---|
| ¿Debería fallar esta ix? | Error | Err(MyError::..) / require! | Decodificar código; bloquear envío ante fallo de simulación |
| ¿Qué paso se ejecutó? | Registro | msg! / vlog con control de características | Explorador / sim logMessages |
| ¿Qué hecho de negocio deberían almacenar los indexadores? | Evento | emit! / sol_log_data | Complemento Geyser, indexador personalizado |
| ¿El estado es correcto después del éxito? | Datos de cuenta | Escrituras bajo reglas del propietario | RPC getAccount / suscripciones |
Los errores deciden el flujo de control. Los registros explican a los ingenieros. Los eventos alimentan a las máquinas. El estado de la cuenta resuelve disputas. Mezclar esos trabajos (por ejemplo, analizar registros de texto libre para contabilidad crítica) crea sistemas frágiles.
Los límites de CPI complican el panorama. Cuando tu programa invoca a otro, el error del llamado puede aparecer en los registros externos. Mapea cuidadosamente: relanza, envuelve en tu propio código de UX o deja el código del llamado para que los exploradores multi-programa se mantengan honestos. Siempre decodifica con (program_id, code), no solo con el código.
Seguridad y UX tiran en direcciones opuestas. Los errores granulares ayudan a los usuarios a corregir las entradas; los excesivamente granulares pueden enseñar a los atacantes qué verificación falló. Prefiere categorías estables sobre mensajes de producción de "volcado de depuración". Coloca detalles de caza de exploits detrás de registros no mainnet controlados, no cadenas #[msg] permanentes.
El presupuesto de cómputo importa en mercados y rutas multi-salto. Los fallos que aparecen solo bajo carga debido a spam de registros son una clase de incidente real. Perfila la CU en simulación después de las actualizaciones (este sitio fija Agave 4.1.1) y trata la eliminación de registros como un cambio de rendimiento legítimo.
El versionado une el binario del programa, el IDL y la tabla de errores. Los programas raramente actualizados congelan la API de errores; planifica los códigos con anticipación. Los programas actualizables deben archivar los artefactos decodificadores por despliegue para que las transacciones históricas sigan siendo explicables.
Las pruebas deben afirmar códigos, no solo el éxito. Las pruebas de LiteSVM y Anchor que esperan Custom(6001) detectan reenumeraciones silenciosas. Las pruebas de cliente deben decodificar errores de simulación de prueba de la misma manera que lo hace producción.
| Enfoque | Fortaleza | Debilidad | Mejor ajuste |
|---|---|---|---|
Solo ProgramError incorporado | Simple, portátil | UX de producto débil | Herramientas internas, prototipos tempranos |
| Enumeraciones personalizadas + IDL | UX estable, listo para i18n | Debe versionarse cuidadosamente | Protocolos visibles para el usuario |
msg! intensivo en todas partes | Depuración local rápida | CU, ruido, datos públicos | Compilaciones de desarrollo, incidentes cortos |
| Eventos estructurados | Esquema amigable para indexadores | Mantenimiento de CU + esquema | Telemetría de protocolo, análisis |
| Simulación + decodificación en dApp | Mejor mensajería para el usuario | Requiere tablas mantenidas | Billeteras, UIs de comercio, herramientas de soporte |
u32 estables y decodifícalos tú mismo.msg! gasta unidades de cómputo y puede causar fallos en presupuestos ajustados.Un error falla la instrucción con un código y revierte el estado. Un registro es una línea de texto libre en los metadatos de la transacción para humanos. Un evento es una carga útil tipificada escrita en los registros para que los indexadores puedan decodificar campos de manera confiable.
Para que el runtime pueda confirmar en Ok(()) o abortar toda la transacción en Err(ProgramError), manteniendo la atomicidad de múltiples instrucciones.
Cuando el fallo es específico del dominio y los clientes necesitan un código estable y con nombre para UX o automatización. Usa los incorporados para problemas genéricos de argumento inválido o cuenta que realmente coincidan con esa semántica.
Las enumeraciones #[error_code] se exportan en el IDL con códigos numéricos que convencionalmente comienzan en 6000, más cadenas de mensajes opcionales para herramientas.
El registro es una llamada al sistema de runtime; más llamadas y cadenas más grandes consumen más del presupuesto de cómputo de la transacción, lo que puede hacer que la instrucción falle si el presupuesto es ajustado.
Generalmente no. Prefiere registros detallados con control de características, breves puntos de referencia permanentes solo donde el valor de operaciones sea alto y eventos estructurados para necesidades de indexadores.
Las instrucciones fallidas no confirman el estado del programa. Diseña la UX de fallos en torno a códigos de error y los registros capturados hasta el punto de fallo, no en torno a cuentas "de eventos de error" duraderas a menos que construyas eso deliberadamente en una ruta de éxito.
Emparejan el código personalizado de la simulación o los metadatos confirmados con el IDL o las tablas de errores generadas, idealmente fijadas a la versión del programa con la que habla tu aplicación.
Determina si aterrizó y se ejecutó. Si es así, recupera los registros y el código de error (o simula el mismo mensaje). Si nunca se ejecutó, depura primero las tarifas, el hash de bloque y la ruta de aterrizaje.
Recorre la pila de invocación de registros, identifica qué ID de programa falló y luego mapea la tabla de códigos de ese programa. Nunca asumas que un entero desnudo es tuyo.
No para rutas controladas por el usuario. Los pánicos abortan sin una API de error de producto limpia y son más difíciles de mapear en clientes. Devuelve Err con un código deliberado.
Son complementarios. Los eventos proporcionan hechos explícitos del dominio; las suscripciones de cuenta proporcionan diferencias de estado. Muchos pipelines de producción usan ambos.
Publica IDL o errors.json en CI junto con el artefacto del programa, versiona con el hash de despliegue y rechaza lanzamientos de clientes que fijan la tabla incorrecta.
Fuera de la cadena. Mapea códigos estables a cadenas de localización en el cliente; no confíes en las cadenas #[msg] en inglés en la cadena como único texto para el usuario.
Los canales de runtime son los mismos: ProgramError, llamadas al sistema de registro y datos de registro binarios opcionales. Eres dueño de más de la historia de publicación de IDL/tabla sin las macros de Anchor.
Versiones de la pila: Esta página fue escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, Rust 1.91.1 y @solana/kit 7.0.0.
Revisado por Chris St. John·Última actualización: 19 jul 2026