Error Handling Patterns

<h2 id="error-handling-in-geode" class="position-relative d-flex align-items-center group"> Error Handling in Geode <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-handling-in-geode" aria-haspopup="dialog" aria-label="Share link: Error Handling in Geode"> Share link </button> </h2><div id="headingShareModal" class="heading-share-modal" role="dialog" aria-modal="true" aria-labelledby="headingShareTitle" hidden> <div class="hsm-dialog" role="document"> <div class="hsm-header"> <h2 id="headingShareTitle" class="h6 mb-0 fw-bold">Share this section</h2> <button type="button" class="hsm-close" aria-label="Close"> </button> </div> <div class="hsm-body"> <label for="headingShareInput" class="form-label small text-muted mb-1 text-uppercase fw-bold" style="font-size: 0.7rem; letter-spacing: 0.5px;">Permalink</label> <div class="input-group mb-4 hsm-url-group"> <input id="headingShareInput" type="text" class="form-control font-monospace" readonly aria-readonly="true" style="font-size: 0.85rem;" /> <button class="btn btn-primary hsm-copy" type="button" aria-label="Copy" title="Copy"> </button> </div> <div class="small fw-bold mb-2 text-muted text-uppercase" style="font-size: 0.7rem; letter-spacing: 0.5px;">Share via</div> <div class="hsm-share-grid"> <a id="share-twitter" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Twitter </a> <a id="share-linkedin" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> LinkedIn </a> <a id="share-facebook" class="btn btn-outline-secondary w-100" target="_blank" rel="noopener noreferrer"> Facebook </a> </div> </div> </div> </div> <style> .heading-share-modal { position: fixed; inset: 0; display: flex; justify-content: center; align-items: center; background: rgba(0, 0, 0, 0.6); z-index: 1050; padding: 1rem; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px); } .heading-share-modal[hidden] { display: none !important; } .hsm-dialog { max-width: 420px; width: 100%; background: var(--bs-body-bg, #fff); color: var(--bs-body-color, #212529); border: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); border-radius: 1rem; box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25); overflow: hidden; animation: hsm-fade-in 0.2s ease-out; } @keyframes hsm-fade-in { from { opacity: 0; transform: scale(0.95); } to { opacity: 1; transform: scale(1); } } [data-bs-theme="dark"] .hsm-dialog { background: #1e293b; border-color: rgba(255,255,255,0.1); color: #f8f9fa; } .hsm-header { display: flex; justify-content: space-between; align-items: center; padding: 1rem 1.5rem; border-bottom: 1px solid var(--bs-border-color, rgba(0,0,0,0.1)); background: rgba(0,0,0,0.02); } [data-bs-theme="dark"] .hsm-header { background: rgba(255,255,255,0.02); border-color: rgba(255,255,255,0.1); } .hsm-close { background: transparent; border: none; color: inherit; opacity: 0.5; padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: 1.2rem; line-height: 1; transition: opacity 0.2s; } .hsm-close:hover { opacity: 1; } .hsm-body { padding: 1.5rem; } .hsm-url-group { display: flex !important; align-items: stretch; } .hsm-url-group .form-control { flex: 1; min-width: 0; margin: 0; background: var(--bs-secondary-bg, #f8f9fa); border-color: var(--bs-border-color, #dee2e6); border-top-right-radius: 0; border-bottom-right-radius: 0; height: 42px; } .hsm-url-group .btn { flex: 0 0 auto; margin: 0; margin-left: -1px; border-top-left-radius: 0; border-bottom-left-radius: 0; height: 42px; display: flex; align-items: center; justify-content: center; padding: 0 1.25rem; z-index: 2; } [data-bs-theme="dark"] .hsm-url-group .form-control { background: #0f172a; border-color: #334155; color: #e2e8f0; } .hsm-share-grid { display: flex; flex-direction: column; gap: 0.5rem; } .hsm-share-grid .btn { display: flex; align-items: center; justify-content: center; font-size: 0.9rem; padding: 0.6rem; border-color: var(--bs-border-color); width: 100%; } [data-bs-theme="dark"] .hsm-share-grid .btn { color: #e2e8f0; border-color: #475569; } [data-bs-theme="dark"] .hsm-share-grid .btn:hover { background: #334155; border-color: #cbd5e1; } </style> <script> (function(){ const modal = document.getElementById('headingShareModal'); if(!modal) return; const input = modal.querySelector('#headingShareInput'); const copyBtn = modal.querySelector('.hsm-copy'); const twitter = modal.querySelector('#share-twitter'); const linkedin = modal.querySelector('#share-linkedin'); const facebook = modal.querySelector('#share-facebook'); const closeBtn = modal.querySelector('.hsm-close'); let lastFocus=null; let trapBound=false; function buildUrl(id){ return window.location.origin + window.location.pathname + '#' + id; } function isOpen(){ return !modal.hasAttribute('hidden'); } function hydrate(id){ const url=buildUrl(id); input.value=url; const enc=encodeURIComponent(url); const text=encodeURIComponent(document.title); if(twitter) twitter.href=`https://twitter.com/intent/tweet?url=${enc}&text=${text}`; if(linkedin) linkedin.href=`https://www.linkedin.com/sharing/share-offsite/?url=${enc}`; if(facebook) facebook.href=`https://www.facebook.com/sharer/sharer.php?u=${enc}`; } function openModal(id){ lastFocus=document.activeElement; hydrate(id); if(!isOpen()){ modal.removeAttribute('hidden'); } requestAnimationFrame(()=>{ input.focus(); }); trapFocus(); } function closeModal(){ if(!isOpen()) return; modal.setAttribute('hidden',''); if(lastFocus && typeof lastFocus.focus==='function') lastFocus.focus(); } function copyCurrent(){ try{ navigator.clipboard.writeText(input.value).then(()=>feedback(true),()=>fallback()); } catch(e){ fallback(); } } function fallback(){ input.select(); try{ document.execCommand('copy'); feedback(true);}catch(e){ feedback(false);} } function feedback(ok){ if(!copyBtn) return; const icon=copyBtn.querySelector('i'); if(!icon) return; const prev=copyBtn.getAttribute('data-prev')||icon.className; if(!copyBtn.getAttribute('data-prev')) copyBtn.setAttribute('data-prev',prev); icon.className= ok ? 'fa-duotone fa-clipboard-check':'fa-duotone fa-circle-exclamation'; setTimeout(()=>{ icon.className=prev; },1800); } function handleShareClick(e){ e.preventDefault(); const btn=e.currentTarget; const id=btn.getAttribute('data-share-target'); if(id) openModal(id); } function bindShareButtons(){ document.querySelectorAll('.h-share').forEach(btn=>{ if(!btn.dataset.hShareBound){ btn.addEventListener('click', handleShareClick); btn.dataset.hShareBound='1'; } }); } bindShareButtons(); if(document.readyState==='loading'){ document.addEventListener('DOMContentLoaded', bindShareButtons); } else { requestAnimationFrame(bindShareButtons); } document.addEventListener('click', function(e){ const shareBtn=e.target.closest && e.target.closest('.h-share'); if(shareBtn && !shareBtn.dataset.hShareBound){ handleShareClick.call(shareBtn, e); } }, true); document.addEventListener('click', e=>{ if(e.target===modal) closeModal(); if(e.target.closest && e.target.closest('.hsm-close')){ e.preventDefault(); closeModal(); } if(copyBtn && (e.target===copyBtn || (e.target.closest && e.target.closest('.hsm-copy')))) { e.preventDefault(); copyCurrent(); } }); document.addEventListener('keydown', e=>{ if(e.key==='Escape' && isOpen()) closeModal(); }); function trapFocus(){ if(trapBound) return; trapBound=true; modal.addEventListener('keydown', f=>{ if(f.key==='Tab' && isOpen()){ const focusable=[...modal.querySelectorAll('a[href],button,input,textarea,select,[tabindex]:not([tabindex="-1"])')].filter(el=>!el.hasAttribute('disabled')); if(!focusable.length) return; const first=focusable[0]; const last=focusable[focusable.length-1]; if(f.shiftKey && document.activeElement===first){ f.preventDefault(); last.focus(); } else if(!f.shiftKey && document.activeElement===last){ f.preventDefault(); first.focus(); } } }); } if(closeBtn) closeBtn.addEventListener('click', e=>{ e.preventDefault(); closeModal(); }); })(); </script>Robust error handling is essential for building reliable applications with Geode. This guide covers the GQL error system, client library exception handling, retry strategies, and best practices for graceful error recovery. Geode implements ISO/IEC 39075:2024 compliant error codes, providing standardized error classification across all client libraries. Understanding these errors enables you to build applications that handle failures gracefully and provide meaningful feedback to users. <h3 id="gql-error-code-system" class="position-relative d-flex align-items-center group"> GQL Error Code System <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="gql-error-code-system" aria-haspopup="dialog" aria-label="Share link: GQL Error Code System"> Share link </button> </h3>Geode uses a hierarchical error code system based on the ISO/IEC 39075:2024 standard. <h4 id="error-code-structure" class="position-relative d-flex align-items-center group"> Error Code Structure <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-code-structure" aria-haspopup="dialog" aria-label="Share link: Error Code Structure"> Share link </button> </h4>Error codes follow the format: <code>GQLXX-YYZZZ</code> <ul> <li><code>GQL</code> - Prefix indicating GQL standard error</li> <li><code>XX</code> - Error category (00-99)</li> <li><code>YY</code> - Error subcategory</li> <li><code>ZZZ</code> - Specific error code</li> </ul> <h4 id="common-error-categories" class="position-relative d-flex align-items-center group"> Common Error Categories <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="common-error-categories" aria-haspopup="dialog" aria-label="Share link: Common Error Categories"> Share link </button> </h4><table> <thead> <tr> <th>Category</th> <th>Code Range</th> <th>Description</th> </tr> </thead> <tbody> <tr> <td>Syntax</td> <td>GQL00-*</td> <td>Query parsing and syntax errors</td> </tr> <tr> <td>Semantic</td> <td>GQL01-*</td> <td>Query semantic validation errors</td> </tr> <tr> <td>Constraint</td> <td>GQL02-*</td> <td>Schema and constraint violations</td> </tr> <tr> <td>Transaction</td> <td>GQL03-*</td> <td>Transaction-related errors</td> </tr> <tr> <td>Security</td> <td>GQL04-*</td> <td>Authentication and authorization errors</td> </tr> <tr> <td>Resource</td> <td>GQL05-*</td> <td>Resource limits and availability</td> </tr> <tr> <td>Data</td> <td>GQL06-*</td> <td>Data type and format errors</td> </tr> <tr> <td>Internal</td> <td>GQL07-*</td> <td>Internal server errors</td> </tr> </tbody> </table> <h3 id="error-response-format" class="position-relative d-flex align-items-center group"> Error Response Format <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-response-format" aria-haspopup="dialog" aria-label="Share link: Error Response Format"> Share link </button> </h3><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json">{ "error": { "code": "GQL02-00001", "message": "Constraint violation: unique constraint on User(email) violated", "details": { "constraint": "user_email_unique", "label": "User", "property": "email", "value": "[email protected]" }, "position": { "line": 3, "column": 1 } } } </code></pre></div> <h3 id="common-error-types" class="position-relative d-flex align-items-center group"> Common Error Types <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="common-error-types" aria-haspopup="dialog" aria-label="Share link: Common Error Types"> Share link </button> </h3> <h4 id="syntax-errors" class="position-relative d-flex align-items-center group"> Syntax Errors <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="syntax-errors" aria-haspopup="dialog" aria-label="Share link: Syntax Errors"> Share link </button> </h4>Occur when a query cannot be parsed. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Error: GQL00-00001 - Unexpected token MTCH (n:User) RETURN n; -- 'MTCH' is not a valid keyword -- Error: GQL00-00010 - Missing clause MATCH (n:User); -- Missing RETURN clause -- Error: GQL00-00020 - Invalid pattern MATCH (a)-[r]-(b) RETURN r; -- Undirected relationships must specify type or use -- </code></pre></div> <h4 id="semantic-errors" class="position-relative d-flex align-items-center group"> Semantic Errors <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="semantic-errors" aria-haspopup="dialog" aria-label="Share link: Semantic Errors"> Share link </button> </h4>Occur when a query is syntactically valid but semantically incorrect. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Error: GQL01-00001 - Undefined variable MATCH (n:User) RETURN m.name; -- Variable 'm' is not defined -- Error: GQL01-00010 - Type mismatch MATCH (n:User) WHERE n.age = 'thirty'; -- Cannot compare integer to string -- Error: GQL01-00020 - Invalid aggregation MATCH (n:User) RETURN n.name, COUNT(n); -- Non-aggregated column 'n.name' without GROUP BY </code></pre></div> <h4 id="constraint-violations" class="position-relative d-flex align-items-center group"> Constraint Violations <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="constraint-violations" aria-haspopup="dialog" aria-label="Share link: Constraint Violations"> Share link </button> </h4>Occur when data modifications violate schema constraints. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Error: GQL02-00001 - Unique constraint violation CREATE (u:User {email: 'existing@example.com'}); -- Email already exists -- Error: GQL02-00010 - NOT NULL violation CREATE (u:User {email: null}); -- email cannot be null -- Error: GQL02-00020 - Check constraint violation CREATE (u:User {age: -5}); -- age must be non-negative </code></pre></div> <h4 id="transaction-errors" class="position-relative d-flex align-items-center group"> Transaction Errors <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="transaction-errors" aria-haspopup="dialog" aria-label="Share link: Transaction Errors"> Share link </button> </h4>Occur during transaction processing. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Error: GQL03-00001 - Serialization failure -- Concurrent transaction modified the same data MATCH (account:Account {id: 'acc_001'}) SET account.balance = account.balance - 100; -- Error: GQL03-00010 - Deadlock detected -- Two transactions waiting on each other -- Error: GQL03-00020 - Transaction timeout -- Transaction exceeded maximum duration </code></pre></div> <h4 id="security-errors" class="position-relative d-flex align-items-center group"> Security Errors <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="security-errors" aria-haspopup="dialog" aria-label="Share link: Security Errors"> Share link </button> </h4>Occur during authentication or authorization checks. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Error: GQL04-00001 - Authentication failed -- Invalid credentials -- Error: GQL04-00010 - Authorization denied MATCH (n:ConfidentialData) RETURN n; -- User does not have access to ConfidentialData -- Error: GQL04-00020 - Session expired -- Authentication token has expired </code></pre></div> <h4 id="resource-errors" class="position-relative d-flex align-items-center group"> Resource Errors <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="resource-errors" aria-haspopup="dialog" aria-label="Share link: Resource Errors"> Share link </button> </h4>Occur when system resources are exhausted. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Error: GQL05-00001 - Connection limit exceeded -- Maximum connections reached -- Error: GQL05-00010 - Memory limit exceeded -- Query requires too much memory -- Error: GQL05-00020 - Query timeout -- Query exceeded maximum execution time </code></pre></div> <h3 id="client-library-error-handling" class="position-relative d-flex align-items-center group"> Client Library Error Handling <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="client-library-error-handling" aria-haspopup="dialog" aria-label="Share link: Client Library Error Handling"> Share link </button> </h3> <h4 id="python-client" class="position-relative d-flex align-items-center group"> Python Client <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="python-client" aria-haspopup="dialog" aria-label="Share link: Python Client"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from geode_client import Client from geode_client.exceptions import ( GeodeError, SyntaxError, SemanticError, ConstraintViolation, TransactionError, SerializationError, AuthenticationError, AuthorizationError, ConnectionError, TimeoutError, ) async def handle_errors(): client = Client(host="localhost", port=3141) try: async with client.connection() as conn: result, _ = await conn.query(""" MATCH (u:User {id: $id}) RETURN u.name, u.email """, {'id': 'user_001'}) for row in result.rows: print(row) except SyntaxError as e: print(f"Query syntax error at line {e.line}, column {e.column}") print(f"Message: {e.message}") except SemanticError as e: print(f"Semantic error: {e.message}") print(f"Error code: {e.code}") except ConstraintViolation as e: print(f"Constraint violation: {e.constraint_name}") print(f"Details: {e.details}") except SerializationError as e: print("Transaction conflict - retry recommended") # Implement retry logic except TransactionError as e: print(f"Transaction failed: {e.message}") # Transaction has been rolled back except AuthenticationError as e: print("Authentication failed - check credentials") except AuthorizationError as e: print(f"Access denied: {e.message}") except ConnectionError as e: print(f"Connection failed: {e.message}") # Consider retry with backoff except TimeoutError as e: print(f"Operation timed out after {e.timeout_ms}ms") except GeodeError as e: # Catch-all for other Geode errors print(f"Geode error [{e.code}]: {e.message}") async def error_recovery_pattern(): """Demonstrate error recovery with retry logic.""" client = Client(host="localhost", port=3141) max_retries = 3 base_delay = 0.1 # 100ms for attempt in range(max_retries): try: async with client.connection() as conn: await conn.begin() try: await conn.execute(""" MATCH (account:Account {id: $id}) SET account.balance = account.balance - $amount """, {'id': 'acc_001', 'amount': 100}) await conn.commit() return True # Success except Exception: await conn.rollback() raise except SerializationError: if attempt < max_retries - 1: delay = base_delay * (2 ** attempt) # Exponential backoff await asyncio.sleep(delay) continue raise except (ConnectionError, TimeoutError): if attempt < max_retries - 1: delay = base_delay * (2 ** attempt) await asyncio.sleep(delay) continue raise return False </code></pre></div> <h4 id="go-client" class="position-relative d-flex align-items-center group"> Go Client <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="go-client" aria-haspopup="dialog" aria-label="Share link: Go Client"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">package main import ( "context" "database/sql" "errors" "log" "time" "geodedb.com/geode" geode_errors "geodedb.com/geode/errors" ) func handleErrors(ctx context.Context, db *sql.DB) { _, err := db.ExecContext(ctx, ` MATCH (u:User {id: $1}) SET u.name = $2 `, "user_001", "Alice") if err == nil { return } // Check specific error types var geodeErr *geode_errors.GeodeError if errors.As(err, &geodeErr) { switch geodeErr.Category() { case geode_errors.CategorySyntax: log.Printf("Syntax error at line %d: %s", geodeErr.Line(), geodeErr.Message()) case geode_errors.CategorySemantic: log.Printf("Semantic error: %s", geodeErr.Message()) case geode_errors.CategoryConstraint: log.Printf("Constraint violation: %s", geodeErr.Details()["constraint"]) case geode_errors.CategoryTransaction: if geodeErr.Code() == "GQL03-00001" { log.Println("Serialization conflict - retry recommended") } else { log.Printf("Transaction error: %s", geodeErr.Message()) } case geode_errors.CategorySecurity: log.Printf("Security error: %s", geodeErr.Message()) case geode_errors.CategoryResource: log.Printf("Resource error: %s", geodeErr.Message()) default: log.Printf("Geode error [%s]: %s", geodeErr.Code(), geodeErr.Message()) } return } // Check for connection errors if errors.Is(err, sql.ErrConnDone) { log.Println("Connection closed") return } // Unknown error log.Printf("Unexpected error: %v", err) } func executeWithRetry(ctx context.Context, db *sql.DB, query string, args ...interface{}) error { maxRetries := 3 baseDelay := 100 * time.Millisecond for attempt := 0; attempt < maxRetries; attempt++ { _, err := db.ExecContext(ctx, query, args...) if err == nil { return nil } var geodeErr *geode_errors.GeodeError if errors.As(err, &geodeErr) { // Retry on serialization conflicts if geodeErr.Code() == "GQL03-00001" { if attempt < maxRetries-1 { delay := baseDelay * time.Duration(1<<attempt) time.Sleep(delay) continue } } // Retry on transient errors if geodeErr.IsTransient() { if attempt < maxRetries-1 { delay := baseDelay * time.Duration(1<<attempt) time.Sleep(delay) continue } } } return err } return errors.New("max retries exceeded") } func transactionWithErrorHandling(ctx context.Context, db *sql.DB) error { tx, err := db.BeginTx(ctx, nil) if err != nil { return fmt.Errorf("failed to begin transaction: %w", err) } // Ensure rollback on panic defer func() { if r := recover(); r != nil { tx.Rollback() panic(r) } }() // Execute operations _, err = tx.ExecContext(ctx, ` MATCH (account:Account {id: $1}) WHERE account.balance >= $2 SET account.balance = account.balance - $2 `, "acc_001", 100) if err != nil { tx.Rollback() return fmt.Errorf("debit failed: %w", err) } _, err = tx.ExecContext(ctx, ` MATCH (account:Account {id: $1}) SET account.balance = account.balance + $2 `, "acc_002", 100) if err != nil { tx.Rollback() return fmt.Errorf("credit failed: %w", err) } // Commit if err = tx.Commit(); err != nil { return fmt.Errorf("commit failed: %w", err) } return nil } </code></pre></div> <h4 id="rust-client" class="position-relative d-flex align-items-center group"> Rust Client <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="rust-client" aria-haspopup="dialog" aria-label="Share link: Rust Client"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-rust" data-lang="rust">use geode_client::{Client, Value, Error, ErrorKind}; use std::time::Duration; use tokio::time::sleep; async fn handle_errors(client: &Client) -> Result<(), Box<dyn std::error::Error>> { let result = client.query( "MATCH (u:User {id: $id}) RETURN u.name", &[("id", Value::String("user_001".into()))], ).await; match result { Ok(rows) => { for row in rows.rows() { println!("Name: {:?}", row.get::<String>("u.name")?); } } Err(Error { kind, code, message, details, .. }) => { match kind { ErrorKind::Syntax => { eprintln!("Syntax error: {}", message); if let Some(line) = details.get("line") { eprintln!("At line: {}", line); } } ErrorKind::Semantic => { eprintln!("Semantic error [{}]: {}", code, message); } ErrorKind::Constraint => { eprintln!("Constraint violation: {}", message); if let Some(constraint) = details.get("constraint") { eprintln!("Constraint: {}", constraint); } } ErrorKind::Transaction => { if code == "GQL03-00001" { eprintln!("Serialization conflict - consider retry"); } else { eprintln!("Transaction error: {}", message); } } ErrorKind::Security => { eprintln!("Security error: {}", message); } ErrorKind::Resource => { eprintln!("Resource error: {}", message); } ErrorKind::Connection => { eprintln!("Connection error: {}", message); } ErrorKind::Timeout => { eprintln!("Operation timed out"); } _ => { eprintln!("Error [{}]: {}", code, message); } } } } Ok(()) } async fn execute_with_retry<F, T>( mut operation: F, max_retries: u32, ) -> Result<T, Error> where F: FnMut() -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<T, Error>> + Send>>, { let base_delay = Duration::from_millis(100); for attempt in 0..max_retries { match operation().await { Ok(result) => return Ok(result), Err(e) => { let should_retry = matches!( e.kind, ErrorKind::Transaction | ErrorKind::Connection | ErrorKind::Timeout ) && e.is_transient(); if should_retry && attempt < max_retries - 1 { let delay = base_delay * 2u32.pow(attempt); sleep(delay).await; continue; } return Err(e); } } } unreachable!() } // Transaction with error handling async fn transfer_funds( client: &Client, from_account: &str, to_account: &str, amount: f64, ) -> Result<(), Error> { let mut tx = client.begin_transaction().await?; // Debit source account let result = tx.execute( r#" MATCH (account:Account {id: $id}) WHERE account.balance >= $amount SET account.balance = account.balance - $amount RETURN account.balance AS new_balance "#, &[ ("id", Value::String(from_account.into())), ("amount", Value::Float(amount)), ], ).await; match result { Ok(rows) if rows.is_empty() => { tx.rollback().await?; return Err(Error::new( ErrorKind::Constraint, "GQL02-00100", "Insufficient funds or account not found", )); } Err(e) => { tx.rollback().await?; return Err(e); } Ok(_) => {} } // Credit destination account if let Err(e) = tx.execute( r#" MATCH (account:Account {id: $id}) SET account.balance = account.balance + $amount "#, &[ ("id", Value::String(to_account.into())), ("amount", Value::Float(amount)), ], ).await { tx.rollback().await?; return Err(e); } // Commit tx.commit().await?; Ok(()) } </code></pre></div> <h3 id="retry-strategies" class="position-relative d-flex align-items-center group"> Retry Strategies <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="retry-strategies" aria-haspopup="dialog" aria-label="Share link: Retry Strategies"> Share link </button> </h3> <h4 id="exponential-backoff" class="position-relative d-flex align-items-center group"> Exponential Backoff <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="exponential-backoff" aria-haspopup="dialog" aria-label="Share link: Exponential Backoff"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import asyncio import random async def retry_with_exponential_backoff( operation, max_retries=5, base_delay=0.1, max_delay=30.0, jitter=True ): """ Retry an operation with exponential backoff. Args: operation: Async function to retry max_retries: Maximum number of attempts base_delay: Initial delay in seconds max_delay: Maximum delay cap jitter: Add randomness to prevent thundering herd """ last_exception = None for attempt in range(max_retries): try: return await operation() except SerializationError as e: last_exception = e # Always retry serialization conflicts except (ConnectionError, TimeoutError) as e: last_exception = e # Retry transient errors except GeodeError as e: if not e.is_transient: raise # Don't retry non-transient errors last_exception = e if attempt < max_retries - 1: delay = min(base_delay * (2 ** attempt), max_delay) if jitter: delay = delay * (0.5 + random.random()) await asyncio.sleep(delay) raise last_exception </code></pre></div> <h4 id="circuit-breaker-pattern" class="position-relative d-flex align-items-center group"> Circuit Breaker Pattern <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="circuit-breaker-pattern" aria-haspopup="dialog" aria-label="Share link: Circuit Breaker Pattern"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import time from enum import Enum class CircuitState(Enum): CLOSED = "closed" # Normal operation OPEN = "open" # Failing, reject requests HALF_OPEN = "half_open" # Testing if recovered class CircuitBreaker: def __init__( self, failure_threshold=5, recovery_timeout=30, half_open_max_calls=3 ): self.failure_threshold = failure_threshold self.recovery_timeout = recovery_timeout self.half_open_max_calls = half_open_max_calls self.state = CircuitState.CLOSED self.failure_count = 0 self.last_failure_time = None self.half_open_calls = 0 async def execute(self, operation): if self.state == CircuitState.OPEN: if time.time() - self.last_failure_time >= self.recovery_timeout: self.state = CircuitState.HALF_OPEN self.half_open_calls = 0 else: raise CircuitBreakerOpen("Circuit breaker is open") if self.state == CircuitState.HALF_OPEN: if self.half_open_calls >= self.half_open_max_calls: raise CircuitBreakerOpen("Circuit breaker half-open limit reached") self.half_open_calls += 1 try: result = await operation() self._on_success() return result except Exception as e: self._on_failure() raise def _on_success(self): if self.state == CircuitState.HALF_OPEN: self.state = CircuitState.CLOSED self.failure_count = 0 def _on_failure(self): self.failure_count += 1 self.last_failure_time = time.time() if self.failure_count >= self.failure_threshold: self.state = CircuitState.OPEN # Usage circuit_breaker = CircuitBreaker(failure_threshold=5, recovery_timeout=30) async def query_with_circuit_breaker(client, query, params): async def operation(): return await client.query(query, params) return await circuit_breaker.execute(operation) </code></pre></div> <h3 id="error-logging-and-monitoring" class="position-relative d-flex align-items-center group"> Error Logging and Monitoring <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-logging-and-monitoring" aria-haspopup="dialog" aria-label="Share link: Error Logging and Monitoring"> Share link </button> </h3> <h4 id="structured-error-logging" class="position-relative d-flex align-items-center group"> Structured Error Logging <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="structured-error-logging" aria-haspopup="dialog" aria-label="Share link: Structured Error Logging"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import logging import json class GeodeErrorLogger: def __init__(self, logger_name="geode"): self.logger = logging.getLogger(logger_name) def log_error(self, error, context=None): """Log error with structured data.""" log_data = { "error_code": error.code, "error_category": error.category, "message": error.message, "details": error.details, } if context: log_data["context"] = context if hasattr(error, 'query'): log_data["query"] = error.query[:500] # Truncate long queries if error.is_transient: self.logger.warning( "Transient Geode error", extra={"geode_error": log_data} ) else: self.logger.error( "Geode error", extra={"geode_error": log_data} ) # Usage error_logger = GeodeErrorLogger() try: result = await client.query(query, params) except GeodeError as e: error_logger.log_error(e, context={ "operation": "user_lookup", "user_id": user_id }) raise </code></pre></div> <h4 id="metrics-collection" class="position-relative d-flex align-items-center group"> Metrics Collection <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="metrics-collection" aria-haspopup="dialog" aria-label="Share link: Metrics Collection"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">from prometheus_client import Counter, Histogram # Error counters geode_errors = Counter( 'geode_errors_total', 'Total Geode errors', ['error_category', 'error_code'] ) geode_retries = Counter( 'geode_retries_total', 'Total retry attempts', ['operation', 'outcome'] ) query_duration = Histogram( 'geode_query_duration_seconds', 'Query execution time', ['operation'], buckets=[0.01, 0.05, 0.1, 0.5, 1.0, 5.0, 10.0] ) async def monitored_query(client, query, params, operation_name="query"): """Execute query with metrics collection.""" start = time.time() try: result = await client.query(query, params) query_duration.labels(operation=operation_name).observe(time.time() - start) return result except GeodeError as e: geode_errors.labels( error_category=e.category, error_code=e.code ).inc() raise </code></pre></div> <h3 id="debugging-techniques" class="position-relative d-flex align-items-center group"> Debugging Techniques <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="debugging-techniques" aria-haspopup="dialog" aria-label="Share link: Debugging Techniques"> Share link </button> </h3> <h4 id="query-analysis" class="position-relative d-flex align-items-center group"> Query Analysis <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="query-analysis" aria-haspopup="dialog" aria-label="Share link: Query Analysis"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Use EXPLAIN to understand query execution EXPLAIN MATCH (u:User {email: $email})-[:PURCHASED]->(p:Product) RETURN p.name, p.price; -- Use PROFILE for actual execution statistics PROFILE MATCH (u:User)-[:PURCHASED]->(p:Product) WHERE u.created_at > datetime() - DURATION 'P30D' RETURN u.name, COUNT(p) AS purchase_count; </code></pre></div> <h4 id="connection-diagnostics" class="position-relative d-flex align-items-center group"> Connection Diagnostics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="connection-diagnostics" aria-haspopup="dialog" aria-label="Share link: Connection Diagnostics"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">async def diagnose_connection(client): """Run connection diagnostics.""" diagnostics = {} # Test basic connectivity try: await client.ping() diagnostics["connectivity"] = "OK" except Exception as e: diagnostics["connectivity"] = f"FAILED: {e}" # Test authentication try: result, _ = await client.query("RETURN 1 AS test") diagnostics["authentication"] = "OK" except AuthenticationError as e: diagnostics["authentication"] = f"FAILED: {e}" # Test query execution try: result, _ = await client.query("MATCH (n) RETURN COUNT(n) LIMIT 1") diagnostics["query_execution"] = "OK" except Exception as e: diagnostics["query_execution"] = f"FAILED: {e}" return diagnostics </code></pre></div> <h3 id="best-practices" class="position-relative d-flex align-items-center group"> Best Practices <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="best-practices" aria-haspopup="dialog" aria-label="Share link: Best Practices"> Share link </button> </h3> <h4 id="error-handling-principles" class="position-relative d-flex align-items-center group"> Error Handling Principles <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="error-handling-principles" aria-haspopup="dialog" aria-label="Share link: Error Handling Principles"> Share link </button> </h4><ol> <li>Catch specific exceptions: Handle different error types appropriately</li> <li>Implement retry logic: Retry transient errors with backoff</li> <li>Fail fast on permanent errors: Don’t retry non-transient failures</li> <li>Log contextual information: Include query, parameters, timing</li> <li>Monitor error rates: Track errors for alerting and analysis</li> </ol> <h4 id="transaction-error-recovery" class="position-relative d-flex align-items-center group"> Transaction Error Recovery <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="transaction-error-recovery" aria-haspopup="dialog" aria-label="Share link: Transaction Error Recovery"> Share link </button> </h4><ol> <li>Always use try/finally for rollback: Ensure cleanup on failure</li> <li>Implement savepoints: Enable partial rollback for complex transactions</li> <li>Handle serialization conflicts: Retry with exponential backoff</li> <li>Set appropriate timeouts: Prevent resource exhaustion</li> </ol> <h4 id="user-facing-error-messages" class="position-relative d-flex align-items-center group"> User-Facing Error Messages <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="user-facing-error-messages" aria-haspopup="dialog" aria-label="Share link: User-Facing Error Messages"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">def get_user_friendly_message(error): """Convert technical errors to user-friendly messages.""" messages = { "GQL02-00001": "This record already exists. Please try a different value.", "GQL02-00010": "Required information is missing. Please fill in all required fields.", "GQL03-00001": "Your request conflicted with another. Please try again.", "GQL04-00001": "Login failed. Please check your credentials.", "GQL04-00010": "You don't have permission to perform this action.", "GQL05-00020": "The operation took too long. Please try a simpler request.", } return messages.get(error.code, "An unexpected error occurred. Please try again later.") </code></pre></div> <h3 id="related-topics" class="position-relative d-flex align-items-center group"> Related Topics <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="related-topics" aria-haspopup="dialog" aria-label="Share link: Related Topics"> Share link </button> </h3><ul> <li><a href="/tags/troubleshooting/" >Troubleshooting</a> - Debugging guide</li> <li><a href="/tags/client-libraries/" >Client Libraries</a> - Client documentation</li> <li><a href="/tags/transactions/" >Transactions</a> - Transaction management</li> <li><a href="/tags/logging/" >Logging</a> - Logging configuration</li> <li><a href="/tags/monitoring/" >Monitoring</a> - Metrics and alerting</li> <li><a href="/tags/security/" >Security</a> - Authentication and authorization</li> </ul> <h3 id="further-reading" class="position-relative d-flex align-items-center group"> Further Reading <button type="button" class="h-share btn btn-link p-0 text-decoration-none link-secondary opacity-50 hover-opacity-100 transition-all ms-1" data-share-target="further-reading" aria-haspopup="dialog" aria-label="Share link: Further Reading"> Share link </button> </h3><ul> <li>ISO/IEC 39075:2024 Error Code Specification</li> <li>Geode Error Reference Documentation</li> <li>Resilient Application Design Patterns</li> <li>Distributed Systems Error Handling</li> <li>Observability and Error Tracking Best Practices</li> </ul> Browse tagged content for complete error handling documentation and examples.

Popular

Related Articles

Error Handling Guide