12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273 |
- <!DOCTYPE html>
- <html lang="en-US">
- <head>
- <meta charset="utf-8">
- <meta name="viewport" content="width=device-width,initial-scale=1">
- <title>Errors | ⚓ Anchor</title>
- <meta name="generator" content="VuePress 1.8.2">
- <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>⚓ </text></svg>">
- <meta name="description" content="">
- <meta name="theme-color" content="#3eaf7c">
- <meta name="apple-mobile-web-app-capable" content="yes">
- <meta name="apple-mobile-web-app-status-bar-style" content="black">
- <link rel="preload" href="/anchor/assets/css/0.styles.67abccc4.css" as="style"><link rel="preload" href="/anchor/assets/js/app.ccbeed71.js" as="script"><link rel="preload" href="/anchor/assets/js/2.90291299.js" as="script"><link rel="preload" href="/anchor/assets/js/21.583658a7.js" as="script"><link rel="prefetch" href="/anchor/assets/js/10.a81a7d6e.js"><link rel="prefetch" href="/anchor/assets/js/11.646c11f1.js"><link rel="prefetch" href="/anchor/assets/js/12.d30544e0.js"><link rel="prefetch" href="/anchor/assets/js/13.5ce10a15.js"><link rel="prefetch" href="/anchor/assets/js/14.7c49f6b3.js"><link rel="prefetch" href="/anchor/assets/js/15.feb576eb.js"><link rel="prefetch" href="/anchor/assets/js/16.b6cb9e25.js"><link rel="prefetch" href="/anchor/assets/js/17.229ba322.js"><link rel="prefetch" href="/anchor/assets/js/18.34343769.js"><link rel="prefetch" href="/anchor/assets/js/19.108e8035.js"><link rel="prefetch" href="/anchor/assets/js/20.89fd4ee6.js"><link rel="prefetch" href="/anchor/assets/js/3.ff8620f0.js"><link rel="prefetch" href="/anchor/assets/js/4.91948ad2.js"><link rel="prefetch" href="/anchor/assets/js/5.47891694.js"><link rel="prefetch" href="/anchor/assets/js/6.493f79e9.js"><link rel="prefetch" href="/anchor/assets/js/7.32936426.js"><link rel="prefetch" href="/anchor/assets/js/8.9fc829e7.js"><link rel="prefetch" href="/anchor/assets/js/9.525a5964.js">
- <link rel="stylesheet" href="/anchor/assets/css/0.styles.67abccc4.css">
- </head>
- <body>
- <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/anchor/" class="home-link router-link-active"><!----> <span class="site-name">⚓ Anchor</span></a> <div class="links"><div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="https://book.anchor-lang.com" target="_blank" rel="noopener noreferrer" class="nav-link external">
- The Anchor Book
- <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div><div class="nav-item"><a href="https://docs.rs/anchor-lang/latest/anchor_lang/" target="_blank" rel="noopener noreferrer" class="nav-link external">
- Rust
- <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div><div class="nav-item"><a href="https://project-serum.github.io/anchor/ts/index.html" target="_blank" rel="noopener noreferrer" class="nav-link external">
- TypeScript
- <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div><div class="nav-item"><a href="https://github.com/project-serum/anchor" target="_blank" rel="noopener noreferrer" class="nav-link external">
- GitHub
- <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <!----></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="https://book.anchor-lang.com" target="_blank" rel="noopener noreferrer" class="nav-link external">
- The Anchor Book
- <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div><div class="nav-item"><a href="https://docs.rs/anchor-lang/latest/anchor_lang/" target="_blank" rel="noopener noreferrer" class="nav-link external">
- Rust
- <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div><div class="nav-item"><a href="https://project-serum.github.io/anchor/ts/index.html" target="_blank" rel="noopener noreferrer" class="nav-link external">
- TypeScript
- <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div><div class="nav-item"><a href="https://github.com/project-serum/anchor" target="_blank" rel="noopener noreferrer" class="nav-link external">
- GitHub
- <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <!----></nav> <ul class="sidebar-links"><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>Getting Started</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/anchor/getting-started/introduction.html" class="sidebar-link">Introduction</a></li><li><a href="/anchor/getting-started/installation.html" class="sidebar-link">Installing Dependencies</a></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>Teams</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/anchor/getting-started/projects.html" class="sidebar-link">Projects</a></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading open"><span>Tutorials</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/anchor/tutorials/tutorial-0.html" class="sidebar-link">A Minimal Example</a></li><li><a href="/anchor/tutorials/tutorial-1.html" class="sidebar-link">Arguments and Accounts</a></li><li><a href="/anchor/tutorials/tutorial-2.html" class="sidebar-link">Account Constraints and Access Control</a></li><li><a href="/anchor/tutorials/tutorial-3.html" class="sidebar-link">Cross Program Invocations (CPI)</a></li><li><a href="/anchor/tutorials/tutorial-4.html" aria-current="page" class="active sidebar-link">Errors</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/anchor/tutorials/tutorial-4.html#defining-a-program" class="sidebar-link">Defining a Program</a></li><li class="sidebar-sub-header"><a href="/anchor/tutorials/tutorial-4.html#using-the-client" class="sidebar-link">Using the Client</a></li></ul></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>CLI</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/anchor/cli/commands.html" class="sidebar-link">Commands</a></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>Source Verification</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/anchor/getting-started/verification.html" class="sidebar-link">Verifiable Builds</a></li><li><a href="/anchor/getting-started/publishing.html" class="sidebar-link">Publishing Source</a></li></ul></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="errors"><a href="#errors" class="header-anchor">#</a> Errors</h1> <p>If you've ever programmed on a blockchain, you've probably been frustrated by
- either non existant or opaque error codes. Anchor attempts to address this by
- providing the <code>#[error]</code> attribute, which can be used to create typed Errors with
- descriptive messages that automatically propagate to the client.</p> <h2 id="defining-a-program"><a href="#defining-a-program" class="header-anchor">#</a> Defining a Program</h2> <p>For example,</p> <div class="language-rust extra-class"><pre class="language-rust"><code><span class="token keyword">use</span> <span class="token namespace">anchor_lang<span class="token punctuation">::</span>prelude<span class="token punctuation">::</span></span><span class="token operator">*</span><span class="token punctuation">;</span>
- <span class="token attribute attr-name">#[program]</span>
- <span class="token keyword">mod</span> <span class="token module-declaration namespace">errors</span> <span class="token punctuation">{</span>
- <span class="token keyword">use</span> <span class="token keyword">super</span><span class="token punctuation">::</span><span class="token operator">*</span><span class="token punctuation">;</span>
- <span class="token keyword">pub</span> <span class="token keyword">fn</span> <span class="token function-definition function">hello</span><span class="token punctuation">(</span>_ctx<span class="token punctuation">:</span> <span class="token class-name">Context</span><span class="token operator"><</span><span class="token class-name">Hello</span><span class="token operator">></span><span class="token punctuation">)</span> <span class="token punctuation">-></span> <span class="token class-name">Result</span><span class="token operator"><</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token operator">></span> <span class="token punctuation">{</span>
- <span class="token class-name">Err</span><span class="token punctuation">(</span><span class="token class-name">ErrorCode</span><span class="token punctuation">::</span><span class="token class-name">Hello</span><span class="token punctuation">.</span><span class="token function">into</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span>
- <span class="token punctuation">}</span>
- <span class="token punctuation">}</span>
- <span class="token attribute attr-name">#[derive(Accounts)]</span>
- <span class="token keyword">pub</span> <span class="token keyword">struct</span> <span class="token type-definition class-name">Hello</span> <span class="token punctuation">{</span><span class="token punctuation">}</span>
- <span class="token attribute attr-name">#[error]</span>
- <span class="token keyword">pub</span> <span class="token keyword">enum</span> <span class="token type-definition class-name">ErrorCode</span> <span class="token punctuation">{</span>
- <span class="token attribute attr-name">#[msg(<span class="token string">"This is an error message clients will automatically display"</span>)]</span>
- <span class="token class-name">Hello</span><span class="token punctuation">,</span>
- <span class="token punctuation">}</span>
- </code></pre></div><p>Observe the <a href="https://docs.rs/anchor-lang/latest/anchor_lang/attr.error.html" target="_blank" rel="noopener noreferrer">#[error]<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> attribute on the <code>ErrorCode</code> enum. This macro generates two types: an <code>Error</code> and a <code>Result</code>, both of which can be used when returning from your program.</p> <p>To use the <code>Error</code>, you can simply use the user defined <code>ErrorCode</code> with Rust's <a href="https://doc.rust-lang.org/std/convert/trait.From.html" target="_blank" rel="noopener noreferrer">From<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> trait. If you're unfamiliar with <code>From</code>, no worries. Just know that you need to either call
- <code>.into()</code> when using your <code>ErrorCode</code>. Or use Rust's <code>?</code> operator, when returning an error.
- Both of these will automatically convert <em>into</em> the correct <code>Error</code>.</p> <details class="custom-block details"><summary>DETAILS</summary> <p>What's the deal with this From stuff? Well, because the Solana runtime expects a <a href="https://docs.rs/solana-program/1.5.5/solana_program/program_error/enum.ProgramError.html" target="_blank" rel="noopener noreferrer">ProgramError<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> in the return value. The framework needs to wrap the user defined error code into a
- <code>ProgramError::Code</code> variant, before returning. The alternative would be to use the
- <code>ProgramError</code> directly.</p></details> <h2 id="using-the-client"><a href="#using-the-client" class="header-anchor">#</a> Using the Client</h2> <p>When using the client, we get the error message.</p> <div class="language-javascript extra-class"><pre class="language-javascript"><code><span class="token keyword">try</span> <span class="token punctuation">{</span>
- <span class="token keyword">const</span> tx <span class="token operator">=</span> <span class="token keyword">await</span> program<span class="token punctuation">.</span>rpc<span class="token punctuation">.</span><span class="token function">hello</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
- assert<span class="token punctuation">.</span><span class="token function">ok</span><span class="token punctuation">(</span><span class="token boolean">false</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
- <span class="token punctuation">}</span> <span class="token keyword">catch</span> <span class="token punctuation">(</span>err<span class="token punctuation">)</span> <span class="token punctuation">{</span>
- <span class="token keyword">const</span> errMsg <span class="token operator">=</span> <span class="token string">"This is an error message clients will automatically display"</span><span class="token punctuation">;</span>
- assert<span class="token punctuation">.</span><span class="token function">equal</span><span class="token punctuation">(</span>err<span class="token punctuation">.</span><span class="token function">toString</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> errMsg<span class="token punctuation">)</span><span class="token punctuation">;</span>
- <span class="token punctuation">}</span>
- </code></pre></div><p>It's that easy. 😃</p> <p>To run the full example, go <a href="https://github.com/project-serum/anchor/tree/master/examples/tutorial/basic-4" target="_blank" rel="noopener noreferrer">here<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>.</p></div> <footer class="page-edit"><!----> <!----></footer> <div class="page-nav"><p class="inner"><span class="prev">
- ←
- <a href="/anchor/tutorials/tutorial-3.html" class="prev">
- Cross Program Invocations (CPI)
- </a></span> <span class="next"><a href="/anchor/cli/commands.html">
- Commands
- </a>
- →
- </span></p></div> </main></div><div class="global-ui"></div></div>
- <script src="/anchor/assets/js/app.ccbeed71.js" defer></script><script src="/anchor/assets/js/2.90291299.js" defer></script><script src="/anchor/assets/js/21.583658a7.js" defer></script>
- </body>
- </html>
|