Troubleshooting Guide | Geode Database

<h3 id="overview" class="position-relative d-flex align-items-center group"> Overview <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="overview" aria-haspopup="dialog" aria-label="Share link: Overview"> Share link </button> </h3><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>This guide helps you diagnose and resolve common issues with Geode database installation, connectivity, queries, performance, and operations. Issues are organized by category with step-by-step solutions. Quick Links: <ul> <li><a href="https://geodedb.com/docs/guides/troubleshooting/#installation-issues" >Installation Issues</a> </li> <li><a href="https://geodedb.com/docs/guides/troubleshooting/#server-startup-problems" >Server Startup Problems</a> </li> <li><a href="https://geodedb.com/docs/guides/troubleshooting/#connectivity-quic-tls" >Connectivity & QUIC/TLS</a> </li> <li><a href="https://geodedb.com/docs/guides/troubleshooting/#query-errors" >Query Errors</a> </li> <li><a href="https://geodedb.com/docs/guides/troubleshooting/#performance-problems" >Performance Problems</a> </li> <li><a href="https://geodedb.com/docs/guides/troubleshooting/#transaction-issues" >Transaction Issues</a> </li> <li><a href="https://geodedb.com/docs/guides/troubleshooting/#client-library-errors" >Client Library Errors</a> </li> <li><a href="https://geodedb.com/docs/guides/troubleshooting/#error-code-reference" >Error Code Reference</a> </li> </ul> <hr> <h3 id="installation-issues" class="position-relative d-flex align-items-center group"> Installation Issues <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="installation-issues" aria-haspopup="dialog" aria-label="Share link: Installation Issues"> Share link </button> </h3> <h4 id="build-fails-with-zig-version-error" class="position-relative d-flex align-items-center group"> Build Fails with Zig Version Error <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="build-fails-with-zig-version-error" aria-haspopup="dialog" aria-label="Share link: Build Fails with Zig Version Error"> Share link </button> </h4>Symptom: Build fails with error about Zig version mismatch. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check your Zig version zig version # Geode requires Zig 0.1.0+ # Install correct version if needed # On Linux (from ziglang.org): wget https://ziglang.org/download/0.1.0/zig-linux-x86_64-0.1.0.tar.xz tar xf zig-linux-x86_64-0.1.0.tar.xz export PATH="$(pwd)/zig-linux-x86_64-0.1.0:$PATH" # Verify version zig version # Should show 0.1.0 # Rebuild cd geode make clean make build </code></pre></div> <h4 id="missing-dependencies-during-build" class="position-relative d-flex align-items-center group"> Missing Dependencies During Build <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="missing-dependencies-during-build" aria-haspopup="dialog" aria-label="Share link: Missing Dependencies During Build"> Share link </button> </h4>Symptom: Build fails with missing library errors (libssl, etc.). Solution for Ubuntu/Debian: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">sudo apt-get update sudo apt-get install -y \ build-essential \ libssl-dev \ pkg-config \ git \ curl </code></pre></div>Solution for macOS: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">brew install openssl pkg-config </code></pre></div> <h4 id="out-of-memory-during-build" class="position-relative d-flex align-items-center group"> Out of Memory During Build <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="out-of-memory-during-build" aria-haspopup="dialog" aria-label="Share link: Out of Memory During Build"> Share link </button> </h4>Symptom: Build process killed or fails with OOM errors. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># For debug build (requires less memory): make build # For release build (requires ~4GB RAM): # Add swap if needed sudo fallocate -l 4G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile # Then build make release </code></pre></div><hr> <h3 id="server-startup-problems" class="position-relative d-flex align-items-center group"> Server Startup Problems <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="server-startup-problems" aria-haspopup="dialog" aria-label="Share link: Server Startup Problems"> Share link </button> </h3> <h4 id="port-already-in-use" class="position-relative d-flex align-items-center group"> Port Already in Use <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="port-already-in-use" aria-haspopup="dialog" aria-label="Share link: Port Already in Use"> Share link </button> </h4>Symptom: Server fails to start with “address already in use” error. Diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check what's using port 3141 lsof -i :3141 # Or use netstat netstat -tulpn | grep 3141 # Kill the process if it's a stuck Geode instance kill -9 <PID> </code></pre></div>Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Option 1: Use a different port geode serve --listen 0.0.0.0:8443 # Option 2: Stop the conflicting process # If it's an old Geode server: pkill geode # Then start server geode serve --listen 0.0.0.0:3141 </code></pre></div> <h4 id="data-directory-permission-denied" class="position-relative d-flex align-items-center group"> Data Directory Permission Denied <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="data-directory-permission-denied" aria-haspopup="dialog" aria-label="Share link: Data Directory Permission Denied"> Share link </button> </h4>Symptom: Server fails with “permission denied” when accessing data directory. Diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check data directory permissions ls -la /var/geode/data # Check ownership stat /var/geode/data </code></pre></div>Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Option 1: Fix permissions sudo chown -R $USER:$USER /var/geode/data chmod -R 755 /var/geode/data # Option 2: Use a directory you own mkdir -p ~/geode-data geode serve \ --listen 0.0.0.0:3141 \ --data-dir ~/geode-data </code></pre></div> <h4 id="tls-certificate-errors-on-startup" class="position-relative d-flex align-items-center group"> TLS Certificate Errors on Startup <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="tls-certificate-errors-on-startup" aria-haspopup="dialog" aria-label="Share link: TLS Certificate Errors on Startup"> Share link </button> </h4>Symptom: Server fails with “cannot load TLS certificate” or similar. Diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check if certificate files exist ls -la server.crt server.key # Verify certificate is valid openssl x509 -in server.crt -text -noout # Check certificate and key match openssl x509 -noout -modulus -in server.crt | openssl md5 openssl rsa -noout -modulus -in server.key | openssl md5 # These should match </code></pre></div>Solution - Generate Self-Signed Certificate: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Generate self-signed certificate for development openssl req -x509 -newkey rsa:4096 \ -keyout server.key \ -out server.crt \ -days 365 \ -nodes \ -subj "/CN=localhost" # Start server with certificate geode serve \ --listen 0.0.0.0:3141 \ --tls-cert server.crt \ --tls-key server.key </code></pre></div>Solution - Use Let’s Encrypt for Production: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Install certbot sudo apt-get install certbot # Get certificate (requires domain) sudo certbot certonly --standalone -d yourdomain.com # Certificates will be in: # /etc/letsencrypt/live/yourdomain.com/fullchain.pem # /etc/letsencrypt/live/yourdomain.com/privkey.pem # Start server sudo geode serve \ --listen 0.0.0.0:3141 \ --tls-cert /etc/letsencrypt/live/yourdomain.com/fullchain.pem \ --tls-key /etc/letsencrypt/live/yourdomain.com/privkey.pem </code></pre></div> <h4 id="server-crashes-immediately-after-start" class="position-relative d-flex align-items-center group"> Server Crashes Immediately After Start <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="server-crashes-immediately-after-start" aria-haspopup="dialog" aria-label="Share link: Server Crashes Immediately After Start"> Share link </button> </h4>Symptom: Server starts then immediately exits or crashes. Diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Run with debug logging geode serve \ --listen 0.0.0.0:3141 \ --log-level debug # Check system logs journalctl -xe | grep geode # Check for core dumps coredumpctl list geode coredumpctl info <ID> </code></pre></div>Common Causes: <ol> <li>Corrupted data directory: Delete <code>data/</code> and restart</li> <li>Insufficient file descriptors: Increase limits with <code>ulimit -n 65536</code></li> <li>Missing shared libraries: Check <code>ldd geode</code></li> </ol> <hr> <h3 id="connectivity--quictls" class="position-relative d-flex align-items-center group"> Connectivity &amp; QUIC/TLS <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="connectivity--quictls" aria-haspopup="dialog" aria-label="Share link: Connectivity &amp; QUIC/TLS"> Share link </button> </h3> <h4 id="cannot-connect---connection-refused" class="position-relative d-flex align-items-center group"> Cannot Connect - Connection Refused <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="cannot-connect---connection-refused" aria-haspopup="dialog" aria-label="Share link: Cannot Connect - Connection Refused"> Share link </button> </h4>Symptom: Client gets “connection refused” error. Diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Verify server is running ps aux | grep geode # Check if port is listening netstat -tulpn | grep 3141 # Test connectivity telnet localhost 3141 # Check firewall sudo iptables -L | grep 3141 </code></pre></div>Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># If server isn't running, start it geode serve --listen 0.0.0.0:3141 # If firewall is blocking, open port sudo ufw allow 3141/tcp sudo ufw allow 3141/udp # QUIC uses UDP # For remote connections, ensure server binds to 0.0.0.0 # NOT 127.0.0.1 (localhost only) geode serve --listen 0.0.0.0:3141 </code></pre></div> <h4 id="tls-handshake-failures" class="position-relative d-flex align-items-center group"> TLS Handshake Failures <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="tls-handshake-failures" aria-haspopup="dialog" aria-label="Share link: TLS Handshake Failures"> Share link </button> </h4>Symptom: Client fails with “TLS handshake failed” or certificate verification errors. For Development (Self-Signed Certificates): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Python client - disable verification (dev only!) from geode_client import Client client = Client(host="localhost", port=3141, skip_verify=True) # Go client - disable verification (dev only!) db, err := sql.Open("geode", "localhost:3141?insecure_tls_skip_verify=true") # Rust client - disable verification (dev only!) use geode_client::Client; let client = Client::new("localhost", 3141).skip_verify(true); let mut conn = client.connect().await?; </code></pre></div>For Production (Proper CA): <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Provide CA certificate path # Python from geode_client import Client client = Client(host="localhost", port=3141, ca_cert="/path/to/ca.crt") # Go db, err := sql.Open("geode", "localhost:3141?ca=/path/to/ca.crt") # Rust use geode_client::Client; let client = Client::new("localhost", 3141).skip_verify(false); let mut conn = client.connect().await?; </code></pre></div> <h4 id="quic-connection-timeout" class="position-relative d-flex align-items-center group"> QUIC Connection Timeout <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="quic-connection-timeout" aria-haspopup="dialog" aria-label="Share link: QUIC Connection Timeout"> Share link </button> </h4>Symptom: Client times out during connection establishment. Diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check if QUIC port (UDP) is accessible nc -zu <server-ip> 3141 # Check server logs for QUIC errors geode serve --log-level debug 2>&1 | grep QUIC # Verify UDP is not blocked by firewall sudo tcpdump -i any udp port 3141 </code></pre></div>Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Validate UDP connectivity and QUIC MTU settings # Check MTU issues (QUIC requires proper MTU) ping -M do -s 1400 <server-ip> # If MTU is too low, configure on server/network </code></pre></div> <h4 id="connection-pool-exhaustion" class="position-relative d-flex align-items-center group"> Connection Pool Exhaustion <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-pool-exhaustion" aria-haspopup="dialog" aria-label="Share link: Connection Pool Exhaustion"> Share link </button> </h4>Symptom: Client gets “no available connections” or “pool exhausted” error. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Increase max connections on server geode serve \ --listen 0.0.0.0:3141 \ --max-connections 10000 # Increase pool size on client # Go db.SetMaxOpenConns(100) db.SetMaxIdleConns(10) db.SetConnMaxLifetime(time.Hour) # Python from geode_client import ConnectionPool pool = ConnectionPool(host="localhost", port=3141, max_size=100, timeout=30.0) # Rust use geode_client::ConnectionPool; let pool = ConnectionPool::new("localhost", 3141, 100); </code></pre></div><hr> <h3 id="query-errors" class="position-relative d-flex align-items-center group"> Query 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="query-errors" aria-haspopup="dialog" aria-label="Share link: Query Errors"> Share link </button> </h3> <h4 id="syntax-error-unexpected-token" class="position-relative d-flex align-items-center group"> Syntax Error: Unexpected Token <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-error-unexpected-token" aria-haspopup="dialog" aria-label="Share link: Syntax Error: Unexpected Token"> Share link </button> </h4>Symptom: Query fails with <code>GQLSTATUS 42000 - Syntax error</code>. Common Causes & Solutions: 1. Reserved Keywords as Identifiers: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- WRONG: Using reserved keyword without backticks MATCH (return:Person) RETURN return.name -- CORRECT: Use backticks for reserved words MATCH (`return`:Person) RETURN `return`.name </code></pre></div>2. Missing Backticks for Multi-Word Labels: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- WRONG MATCH (n:Social Network) RETURN n -- CORRECT MATCH (n:`Social Network`) RETURN n </code></pre></div>3. Parameter Syntax Errors: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- WRONG: Missing $ for parameters MATCH (n:Person {name: name_param}) RETURN n -- CORRECT: Use $ prefix MATCH (n:Person {name: $name_param}) RETURN n </code></pre></div>Debugging Tip: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Use EXPLAIN to see where parser fails geode query "EXPLAIN <your query here>" </code></pre></div> <h4 id="undefined-object-error" class="position-relative d-flex align-items-center group"> Undefined Object Error <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="undefined-object-error" aria-haspopup="dialog" aria-label="Share link: Undefined Object Error"> Share link </button> </h4>Symptom: <code>GQLSTATUS 42001 - Undefined object</code> or “label not found”. Cause: Referencing nodes/relationships that don’t exist. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- First, check what labels exist MATCH (n) RETURN DISTINCT labels(n) AS existing_labels; -- Create missing labels/nodes CREATE (p:Person {name: "Alice", age: 30}); -- Use MERGE if unsure if node exists MERGE (p:Person {id: 1}) ON CREATE SET p.name = "Alice" ON MATCH SET p.lastSeen = timestamp(); </code></pre></div> <h4 id="type-mismatch-errors" class="position-relative d-flex align-items-center group"> Type Mismatch 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="type-mismatch-errors" aria-haspopup="dialog" aria-label="Share link: Type Mismatch Errors"> Share link </button> </h4>Symptom: <code>GQLSTATUS 22000 - Data exception</code> for type incompatibility. Common Cases: 1. Comparing Incompatible Types: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- WRONG: Comparing string to number MATCH (p:Person) WHERE p.age = "30" RETURN p -- CORRECT: Use consistent types MATCH (p:Person) WHERE p.age = 30 RETURN p </code></pre></div>2. Arithmetic on Non-Numeric Types: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- WRONG RETURN "hello" + 5 -- CORRECT: Convert first RETURN toInt("123") + 5 </code></pre></div>3. NULL Handling: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- NULL comparisons require IS NULL / IS NOT NULL MATCH (p:Person) WHERE p.age IS NOT NULL RETURN p -- Arithmetic with NULL returns NULL RETURN 5 + null -- Returns null </code></pre></div> <h4 id="performance-query-too-slow" class="position-relative d-flex align-items-center group"> Performance: Query Too Slow <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="performance-query-too-slow" aria-haspopup="dialog" aria-label="Share link: Performance: Query Too Slow"> Share link </button> </h4>See <a href="https://geodedb.com/docs/guides/troubleshooting/#performance-problems" >Performance Problems</a> section below. <h4 id="cartesian-product-warning" class="position-relative d-flex align-items-center group"> Cartesian Product Warning <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="cartesian-product-warning" aria-haspopup="dialog" aria-label="Share link: Cartesian Product Warning"> Share link </button> </h4>Symptom: Query generates millions of rows unintentionally. Cause: Multiple <code>MATCH</code> clauses without connecting them. Example of Problem: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- WARNING: Cartesian product (every person × every book) MATCH (p:Person) MATCH (b:Book) RETURN p.name, b.title -- If 1000 people and 1000 books = 1,000,000 rows! </code></pre></div>Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Connect the patterns MATCH (p:Person)-[:READ]->(b:Book) RETURN p.name, b.title -- Or use WHERE to filter MATCH (p:Person), (b:Book) WHERE p.favoriteGenre = b.genre RETURN p.name, b.title </code></pre></div><hr> <h3 id="performance-problems" class="position-relative d-flex align-items-center group"> Performance Problems <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="performance-problems" aria-haspopup="dialog" aria-label="Share link: Performance Problems"> Share link </button> </h3> <h4 id="slow-query-execution" class="position-relative d-flex align-items-center group"> Slow Query Execution <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="slow-query-execution" aria-haspopup="dialog" aria-label="Share link: Slow Query Execution"> Share link </button> </h4>Step 1: Identify the Problem <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Use PROFILE to see execution metrics geode query "PROFILE MATCH (n:Person) RETURN n" </code></pre></div>Step 2: Analyze Query Plan <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Use EXPLAIN to see query plan geode query "EXPLAIN MATCH (n:Person WHERE n.age > 30) RETURN n" # Look for: # - "Scan" without index (bad for large datasets) # - Large "EstimatedRows" counts # - Missing index usage </code></pre></div>Step 3: Add Indexes <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create index on frequently queried properties CREATE INDEX person_age ON Person(age); CREATE INDEX person_name ON Person(name); -- For full-text search CREATE FULLTEXT INDEX person_bio ON Person(bio); -- For spatial queries CREATE SPATIAL INDEX location_coords ON Location(coordinates); -- For vector similarity CREATE VECTOR INDEX doc_embedding ON Document(embedding); -- Verify indexes exist SHOW INDEXES; </code></pre></div>Step 4: Rewrite Inefficient Queries <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- SLOW: Filtering after collecting all data MATCH (p:Person) WHERE p.age > 30 RETURN p -- FASTER: Use index-backed property filter in MATCH MATCH (p:Person {age: 30}) -- Exact match uses index RETURN p -- For ranges, ensure index exists first CREATE INDEX person_age ON Person(age); -- Then query MATCH (p:Person) WHERE p.age > 30 RETURN p </code></pre></div> <h4 id="high-memory-usage" class="position-relative d-flex align-items-center group"> High Memory Usage <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="high-memory-usage" aria-haspopup="dialog" aria-label="Share link: High Memory Usage"> Share link </button> </h4>Diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Monitor server memory ps aux | grep geode # Check page cache size geode serve --page-cache-size 512 # MB # Monitor with metrics curl http://localhost:9090/metrics | grep memory </code></pre></div>Solutions: 1. Reduce Page Cache: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Default is 1024MB, reduce if needed geode serve \ --listen 0.0.0.0:3141 \ --page-cache-size 256 </code></pre></div>2. Limit Query Results: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Always use LIMIT for large result sets MATCH (n) RETURN n LIMIT 1000 -- Use pagination MATCH (n:Person) RETURN n ORDER BY n.id SKIP 1000 LIMIT 100 </code></pre></div>3. Use Streaming for Large Data: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Python - stream results instead of loading all for row in client.rows.query_stream("MATCH (n:Person) RETURN n"): process(row) # Process one row at a time </code></pre></div> <h4 id="index-not-being-used" class="position-relative d-flex align-items-center group"> Index Not Being Used <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="index-not-being-used" aria-haspopup="dialog" aria-label="Share link: Index Not Being Used"> Share link </button> </h4>Diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check if index exists geode query "SHOW INDEXES" # Use EXPLAIN to see if index is used geode query " EXPLAIN MATCH (p:Person WHERE p.email = '[email protected]') RETURN p " # Look for "IndexSeek" or "IndexScan" in plan # If you see "NodeScan", index is NOT being used </code></pre></div>Common Reasons Index Isn’t Used: 1. Index doesn’t exist for that property: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Create it CREATE INDEX person_email ON Person(email); </code></pre></div>2. Query pattern doesn’t match index: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Index on "name" won't help this query: MATCH (p:Person) WHERE p.email = '...' RETURN p -- Need index on "email": CREATE INDEX person_email ON Person(email); </code></pre></div>3. Function on indexed property: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- WRONG: Function prevents index usage MATCH (p:Person) WHERE toLower(p.name) = 'alice' RETURN p -- BETTER: Store normalized value MATCH (p:Person) WHERE p.normalizedName = 'alice' RETURN p -- Or create expression index (if supported): CREATE INDEX person_name_lower ON Person(toLower(name)); </code></pre></div> <h4 id="slow-aggregations" class="position-relative d-flex align-items-center group"> Slow Aggregations <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="slow-aggregations" aria-haspopup="dialog" aria-label="Share link: Slow Aggregations"> Share link </button> </h4>Problem: <code>count()</code>, <code>sum()</code>, <code>avg()</code> queries are slow. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- SLOW: Count all nodes of a label MATCH (p:Person) RETURN count(p) -- FASTER: If you maintain counts in a separate node MATCH (stats:Statistics {label: 'Person'}) RETURN stats.count -- Update count when adding/removing MATCH (stats:Statistics {label: 'Person'}) SET stats.count = stats.count + 1 </code></pre></div>For Large Aggregations: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Use materialized views (if available) CREATE MATERIALIZED VIEW person_stats AS MATCH (p:Person) RETURN count(p) AS total, avg(p.age) AS avg_age, min(p.age) AS min_age, max(p.age) AS max_age REFRESH COMPLETE; -- Query the view SELECT * FROM person_stats; </code></pre></div><hr> <h3 id="transaction-issues" class="position-relative d-flex align-items-center group"> Transaction Issues <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-issues" aria-haspopup="dialog" aria-label="Share link: Transaction Issues"> Share link </button> </h3> <h4 id="deadlock-detected" class="position-relative d-flex align-items-center group"> Deadlock Detected <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="deadlock-detected" aria-haspopup="dialog" aria-label="Share link: Deadlock Detected"> Share link </button> </h4>Symptom: Transaction fails with deadlock error. Cause: Two or more transactions waiting for each other to release locks. Solution 1: Retry with Exponential Backoff: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import time import random from geode_client import Client, QueryError client = Client(host="localhost", port=3141) async def execute_with_retry(conn, query, max_retries=3): for attempt in range(max_retries): try: await conn.query(query) return except QueryError: if attempt == max_retries - 1: raise # Exponential backoff with jitter wait = (2 ** attempt) + random.uniform(0, 1) time.sleep(wait) # async with client.connection() as conn: # await execute_with_retry(conn, "MATCH (n) RETURN count(n)") </code></pre></div>Solution 2: Consistent Lock Ordering: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- BAD: Inconsistent ordering across transactions -- Transaction 1: Locks Alice, then Bob -- Transaction 2: Locks Bob, then Alice -- = DEADLOCK RISK -- GOOD: Always lock in same order (e.g., by ID) BEGIN TRANSACTION; MATCH (a:Person {id: 1}) MATCH (b:Person {id: 2}) SET a.balance = a.balance - 100, b.balance = b.balance + 100; COMMIT; </code></pre></div> <h4 id="transaction-timeout" class="position-relative d-flex align-items-center group"> Transaction Timeout <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-timeout" aria-haspopup="dialog" aria-label="Share link: Transaction Timeout"> Share link </button> </h4>Symptom: Long-running transaction aborts with timeout. Solution 1: Increase Timeout: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Server-side timeout configuration geode serve \ --listen 0.0.0.0:3141 \ --transaction-timeout 300 # seconds </code></pre></div>Solution 2: Break into Smaller Transactions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># SLOW: One huge transaction async with client.connection() as tx: await tx.begin() for i in range(100000): await tx.execute("CREATE (n:Node {id: $id})", {"id": i}) await tx.commit() # FASTER: Batch into smaller transactions batch_size = 1000 for i in range(0, 100000, batch_size): async with client.connection() as tx: await tx.begin() for j in range(i, min(i + batch_size, 100000)): await tx.execute("CREATE (n:Node {id: $id})", {"id": j}) await tx.commit() </code></pre></div> <h4 id="savepoint-rollback-issues" class="position-relative d-flex align-items-center group"> Savepoint Rollback Issues <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="savepoint-rollback-issues" aria-haspopup="dialog" aria-label="Share link: Savepoint Rollback Issues"> Share link </button> </h4>Symptom: <code>ROLLBACK TO SAVEPOINT</code> doesn’t restore expected state. Common Mistake: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">BEGIN TRANSACTION; CREATE (a:Person {name: "Alice"}); SAVEPOINT sp1; CREATE (b:Person {name: "Bob"}); ROLLBACK TO sp1; -- Bob creation rolled back -- Alice is still there COMMIT; -- Alice persists, Bob does not </code></pre></div>Solution: Understand savepoint scope: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">BEGIN TRANSACTION; SAVEPOINT sp1; CREATE (a:Person {name: "Alice"}); CREATE (b:Person {name: "Bob"}); ROLLBACK TO sp1; -- Both Alice and Bob rolled back CREATE (c:Person {name: "Charlie"}); COMMIT; -- Only Charlie persists </code></pre></div><hr> <h3 id="client-library-errors" class="position-relative d-flex align-items-center group"> Client Library 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="client-library-errors" aria-haspopup="dialog" aria-label="Share link: Client Library Errors"> Share link </button> </h3> <h4 id="python-asyncio-event-loop-errors" class="position-relative d-flex align-items-center group"> Python: asyncio Event Loop 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="python-asyncio-event-loop-errors" aria-haspopup="dialog" aria-label="Share link: Python: asyncio Event Loop Errors"> Share link </button> </h4>Symptom: <code>RuntimeError: Event loop is closed</code> or similar. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python">import asyncio # WRONG: Reusing closed loop loop = asyncio.get_event_loop() loop.run_until_complete(main()) loop.close() loop.run_until_complete(another_func()) # ERROR # CORRECT: Use asyncio.run() asyncio.run(main()) asyncio.run(another_func()) # Or manage loop properly loop = asyncio.new_event_loop() asyncio.set_event_loop(loop) try: loop.run_until_complete(main()) finally: loop.close() </code></pre></div> <h4 id="go-connection-pool-starvation" class="position-relative d-flex align-items-center group"> Go: Connection Pool Starvation <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-connection-pool-starvation" aria-haspopup="dialog" aria-label="Share link: Go: Connection Pool Starvation"> Share link </button> </h4>Symptom: Queries hang or timeout waiting for connection. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">import ( "database/sql" "time" ) db, err := sql.Open("geode", "localhost:3141") if err != nil { log.Fatal(err) } // Configure pool db.SetMaxOpenConns(25) // Max open connections db.SetMaxIdleConns(5) // Idle connections in pool db.SetConnMaxLifetime(5 * time.Minute) // Max lifetime db.SetConnMaxIdleTime(1 * time.Minute) // Max idle time // Always use context with timeout ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second) defer cancel() rows, err := db.QueryContext(ctx, "MATCH (n) RETURN n LIMIT 10") </code></pre></div> <h4 id="rust-quinn-quic-connection-errors" class="position-relative d-flex align-items-center group"> Rust: Quinn QUIC Connection 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="rust-quinn-quic-connection-errors" aria-haspopup="dialog" aria-label="Share link: Rust: Quinn QUIC Connection Errors"> Share link </button> </h4>Symptom: Connection fails with Quinn-specific errors. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-rust" data-lang="rust">use geode_client::{Client, Error}; let client = Client::new("localhost", 3141).skip_verify(false); let mut conn = client.connect().await?; let mut retries = 3; while retries > 0 { match conn.query("MATCH (n) RETURN n LIMIT 10").await { Ok(_) => break, Err(Error::Connection(_)) if retries > 1 => { retries -= 1; tokio::time::sleep(std::time::Duration::from_secs(1)).await; } Err(e) => return Err(e), } } </code></pre></div> <h4 id="zig-memory-allocation-failures" class="position-relative d-flex align-items-center group"> Zig: Memory Allocation Failures <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="zig-memory-allocation-failures" aria-haspopup="dialog" aria-label="Share link: Zig: Memory Allocation Failures"> Share link </button> </h4>Symptom: Zig client panics with OOM or allocation error. Solution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-zig" data-lang="zig">const std = @import("std"); const geode = @import("geode_client"); pub fn main() !void { // Use larger allocator for large result sets var gpa = std.heap.GeneralPurposeAllocator(.{}){}; defer _ = gpa.deinit(); const allocator = gpa.allocator(); var client = try geode.Client.init(allocator, .{ .host = "localhost", .port = 3141, }); defer client.deinit(); // For very large results, use streaming or pagination const result = try client.query( "MATCH (n) RETURN n LIMIT 1000" // Limit result size ); defer result.deinit(); // Process results in batches while (try result.next()) |row| { // Process row // Memory is freed after each iteration } } </code></pre></div><hr> <h3 id="error-code-reference" class="position-relative d-flex align-items-center group"> Error Code Reference <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-reference" aria-haspopup="dialog" aria-label="Share link: Error Code Reference"> Share link </button> </h3> <h4 id="gql-status-codes-iso-standard" class="position-relative d-flex align-items-center group"> GQL Status Codes (ISO Standard) <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-status-codes-iso-standard" aria-haspopup="dialog" aria-label="Share link: GQL Status Codes (ISO Standard)"> Share link </button> </h4><table> <thead> <tr> <th>Code</th> <th>Category</th> <th>Meaning</th> <th>Common Cause</th> </tr> </thead> <tbody> <tr> <td><code>00000</code></td> <td>Success</td> <td>No error</td> <td>Query executed successfully</td> </tr> <tr> <td><code>02000</code></td> <td>No Data</td> <td>Query returned no results</td> <td>Empty result set (not an error)</td> </tr> <tr> <td><code>22000</code></td> <td>Data Exception</td> <td>Type mismatch or invalid data</td> <td>Comparing string to number</td> </tr> <tr> <td><code>42000</code></td> <td>Syntax Error</td> <td>Invalid GQL syntax</td> <td>Missing keyword, typo</td> </tr> <tr> <td><code>42001</code></td> <td>Undefined Object</td> <td>Referenced object doesn’t exist</td> <td>Label/property not found</td> </tr> <tr> <td><code>42002</code></td> <td>Duplicate Object</td> <td>Object already exists</td> <td>Creating duplicate unique constraint</td> </tr> </tbody> </table> <h4 id="internal-error-codes" class="position-relative d-flex align-items-center group"> Internal Error Codes <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="internal-error-codes" aria-haspopup="dialog" aria-label="Share link: Internal Error Codes"> Share link </button> </h4><table> <thead> <tr> <th>Code</th> <th>Meaning</th> <th>Solution</th> </tr> </thead> <tbody> <tr> <td><code>ERR_OOM</code></td> <td>Out of memory</td> <td>Reduce query size, increase server memory</td> </tr> <tr> <td><code>ERR_FLOAT_NAN</code></td> <td>Invalid floating point (NaN)</td> <td>Check calculation logic</td> </tr> <tr> <td><code>ERR_CHAR_LEN</code></td> <td>String exceeds max length</td> <td>Shorten string or increase limit</td> </tr> <tr> <td><code>ERR_DEC_DIV_ZERO</code></td> <td>Division by zero</td> <td>Add zero check before division</td> </tr> <tr> <td><code>ERR_IP_PARSE</code></td> <td>Invalid IP address format</td> <td>Use valid IPv4/IPv6 format</td> </tr> <tr> <td><code>ERR_JSON_PARSE</code></td> <td>Invalid JSON</td> <td>Validate JSON syntax</td> </tr> </tbody> </table> <h4 id="transaction-error-codes" class="position-relative d-flex align-items-center group"> Transaction Error Codes <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-codes" aria-haspopup="dialog" aria-label="Share link: Transaction Error Codes"> Share link </button> </h4><table> <thead> <tr> <th>Error</th> <th>Meaning</th> <th>Solution</th> </tr> </thead> <tbody> <tr> <td><code>DEADLOCK_DETECTED</code></td> <td>Circular wait for locks</td> <td>Retry with backoff</td> </tr> <tr> <td><code>TRANSACTION_TIMEOUT</code></td> <td>Transaction exceeded time limit</td> <td>Break into smaller transactions</td> </tr> <tr> <td><code>SERIALIZATION_FAILURE</code></td> <td>SSI conflict detected</td> <td>Retry transaction</td> </tr> <tr> <td><code>INVALID_SAVEPOINT</code></td> <td>Savepoint name not found</td> <td>Check savepoint spelling</td> </tr> </tbody> </table> <hr> <h3 id="diagnostic-commands" class="position-relative d-flex align-items-center group"> Diagnostic Commands <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="diagnostic-commands" aria-haspopup="dialog" aria-label="Share link: Diagnostic Commands"> Share link </button> </h3> <h4 id="server-health-check" class="position-relative d-flex align-items-center group"> Server Health Check <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="server-health-check" aria-haspopup="dialog" aria-label="Share link: Server Health Check"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check if server is responsive curl http://localhost:9090/health # Check readiness (for K8s) curl http://localhost:9090/ready # View metrics curl http://localhost:9090/metrics </code></pre></div> <h4 id="log-analysis" class="position-relative d-flex align-items-center group"> Log 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="log-analysis" aria-haspopup="dialog" aria-label="Share link: Log Analysis"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># View recent errors journalctl -u geode -n 100 | grep ERROR # Follow logs in real-time journalctl -u geode -f # Filter by severity geode serve --log-level debug 2>&1 | grep -E 'ERROR|WARN' # Search for specific error grep "GQLSTATUS 42000" /var/log/geode/server.log </code></pre></div> <h4 id="connection-testing" class="position-relative d-flex align-items-center group"> Connection Testing <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-testing" aria-haspopup="dialog" aria-label="Share link: Connection Testing"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Test QUIC connectivity (requires netcat with QUIC support) nc -zu <server-ip> 3141 # Test with client geode query "RETURN 1" # Verbose connection debug export GEODE_LOG_LEVEL=debug geode query "RETURN 1" </code></pre></div> <h4 id="performance-profiling" class="position-relative d-flex align-items-center group"> Performance Profiling <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="performance-profiling" aria-haspopup="dialog" aria-label="Share link: Performance Profiling"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Profile a slow query PROFILE MATCH (p:Person)-[:KNOWS*1..3]->(f:Person) WHERE p.name = 'Alice' RETURN f.name, count(*) AS connections ORDER BY connections DESC LIMIT 10; -- Explain query plan EXPLAIN MATCH (p:Person {age: 30}) RETURN p; -- Check current queries (if monitoring enabled) CALL db.currentQueries(); -- Show active transactions CALL db.transactions(); </code></pre></div><hr> <h3 id="getting-help" class="position-relative d-flex align-items-center group"> Getting Help <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="getting-help" aria-haspopup="dialog" aria-label="Share link: Getting Help"> Share link </button> </h3> <h4 id="check-documentation" class="position-relative d-flex align-items-center group"> Check Documentation <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="check-documentation" aria-haspopup="dialog" aria-label="Share link: Check Documentation"> Share link </button> </h4><ul> <li><a href="/guides/installation/" >Installation Guide</a> </li> <li><a href="/docs/configuration/server-configuration/" >Configuration Reference</a> </li> <li><a href="/docs/gql/guide/" >GQL Guide</a> </li> <li><a href="/docs/query/performance-tuning/" >Performance Tuning</a> </li> <li><a href="/docs/security/overview/" >Security Overview</a> </li> </ul> <h4 id="community--support" class="position-relative d-flex align-items-center group"> Community &amp; Support <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="community--support" aria-haspopup="dialog" aria-label="Share link: Community &amp; Support"> Share link </button> </h4><ul> <li>GitLab Issues: <a href="https://gitlab.com/devnw/codepros/geode/geode/issues" aria-label="https://gitlab.com/devnw/codepros/geode/geode/issues – opens in new window" target="_blank" rel="noopener noreferrer" >https://gitlab.com/devnw/codepros/geode/geode/issues ↗ </a> </li> <li>Discussions: <a href="https://gitlab.com/devnw/codepros/geode/geode/discussions" aria-label="https://gitlab.com/devnw/codepros/geode/geode/discussions – opens in new window" target="_blank" rel="noopener noreferrer" >https://gitlab.com/devnw/codepros/geode/geode/discussions ↗ </a> </li> <li>GitLab: <a href="https://gitlab.com/devnw/codepros/geode/" aria-label="https://gitlab.com/devnw/codepros/geode/ – opens in new window" target="_blank" rel="noopener noreferrer" >https://gitlab.com/devnw/codepros/geode/ ↗ </a> </li> </ul> <h4 id="reporting-bugs" class="position-relative d-flex align-items-center group"> Reporting Bugs <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="reporting-bugs" aria-haspopup="dialog" aria-label="Share link: Reporting Bugs"> Share link </button> </h4>When reporting an issue, include: <ol> <li>Geode version: <code>geode --version</code></li> <li>OS and version: <code>uname -a</code></li> <li>Zig version: <code>zig version</code></li> <li>Exact error message with full stack trace</li> <li>Minimal reproducible example of the query/code</li> <li>Server logs around the time of error</li> <li>Configuration (anonymize sensitive data)</li> </ol> Example Bug Report: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-markdown" data-lang="markdown">**Geode Version**: v0.2.18 **OS**: Ubuntu 22.04 LTS **Zig Version**: 0.1.0 **Issue**: Query with CASE expression fails with syntax error **Query**: ```gql MATCH (p:Person) RETURN p.name, CASE WHEN p.age < 30 THEN 'young' ELSE 'senior' END AS category </code></pre></div>Error: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">GQLSTATUS 42000: Syntax error near 'CASE' </code></pre></div>Server Logs: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback">[ERROR] Parser failed at line 2, column 20 </code></pre></div>Expected: Query should categorize people by age Actual: Syntax error <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-fallback" data-lang="fallback"> --- ## Next Steps - [Configuration Reference](/docs/configuration/server-configuration/) - Tune server settings - [Query Performance](/docs/query/performance-tuning/) - Optimize slow queries - [Security Guide](/docs/security/overview/) - Harden production deployment - [Deployment Guide](/docs/ops/deployment/) - Production deployment patterns - [Monitoring](/docs/ops/observability/) - Set up metrics and alerts </code></pre></div>