Troubleshooting Guide

Troubleshooting involves systematically diagnosing and resolving issues that prevent Geode from operating correctly. This comprehensive guide covers common problems, diagnostic techniques, resolution procedures, and preventive measures to maintain optimal database health and minimize downtime. <h3 id="troubleshooting-methodology" class="position-relative d-flex align-items-center group"> Troubleshooting Methodology <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="troubleshooting-methodology" aria-haspopup="dialog" aria-label="Share link: Troubleshooting Methodology"> 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>Effective troubleshooting follows a systematic approach rather than random trial and error. This methodology ensures efficient problem resolution while building understanding of system behavior. <h4 id="diagnostic-process" class="position-relative d-flex align-items-center group"> Diagnostic Process <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-process" aria-haspopup="dialog" aria-label="Share link: Diagnostic Process"> Share link </button> </h4>The standard diagnostic process proceeds through defined steps: <ol> <li>Identify Symptoms - Document observable behavior and error messages</li> <li>Gather Information - Collect logs, metrics, and system state</li> <li>Isolate Variables - Determine what changed before the issue appeared</li> <li>Form Hypothesis - Develop theories about root causes</li> <li>Test Hypothesis - Validate theories through targeted investigation</li> <li>Apply Solution - Implement fixes based on confirmed diagnosis</li> <li>Verify Resolution - Confirm the issue is resolved</li> <li>Document Findings - Record the issue and solution for future reference</li> </ol> <h4 id="information-gathering" class="position-relative d-flex align-items-center group"> Information Gathering <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="information-gathering" aria-haspopup="dialog" aria-label="Share link: Information Gathering"> Share link </button> </h4>Comprehensive information gathering provides the foundation for accurate diagnosis: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># System information uname -a cat /etc/os-release # Geode process status ps aux | grep geode systemctl status geode # Resource usage free -h df -h top -bn1 | head -20 # Network status netstat -tulpn | grep 3141 ss -uln | grep 3141 # Recent logs journalctl -u geode -n 100 --no-pager tail -100 /var/log/geode/geode.log </code></pre></div> <h3 id="connection-issues" class="position-relative d-flex align-items-center group"> Connection 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="connection-issues" aria-haspopup="dialog" aria-label="Share link: Connection Issues"> Share link </button> </h3>Connection problems prevent clients from communicating with Geode. <h4 id="cannot-connect-to-server" class="position-relative d-flex align-items-center group"> Cannot Connect to Server <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-to-server" aria-haspopup="dialog" aria-label="Share link: Cannot Connect to Server"> Share link </button> </h4>Symptoms: Client applications receive connection refused or timeout errors. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Verify server is running systemctl status geode ps aux | grep geode # Check if server is listening netstat -tulpn | grep 3141 ss -uln sport = :3141 # Test local connectivity geode shell </code></pre></div>Common Causes and Solutions: Server Not Running: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check why server stopped journalctl -u geode -n 50 # Start server systemctl start geode # Enable automatic startup systemctl enable geode </code></pre></div>Firewall Blocking Connections: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check firewall status sudo ufw status sudo firewall-cmd --list-all # Allow Geode port (UFW) sudo ufw allow 3141/udp # Allow Geode port (firewalld) sudo firewall-cmd --permanent --add-port=3141/udp sudo firewall-cmd --reload </code></pre></div>Wrong Listen Address: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check configured listen address journalctl -u geode | grep "Listening on" # Reconfigure to listen on all interfaces # Edit /etc/systemd/system/geode.service # Change: --listen 127.0.0.1:3141 # To: --listen 0.0.0.0:3141 sudo systemctl daemon-reload sudo systemctl restart geode </code></pre></div> <h4 id="tlscertificate-errors" class="position-relative d-flex align-items-center group"> TLS/Certificate 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="tlscertificate-errors" aria-haspopup="dialog" aria-label="Share link: TLS/Certificate Errors"> Share link </button> </h4>Symptoms: “TLS handshake failed” or “Certificate verification failed” errors. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Verify certificate exists and is readable ls -l /etc/geode/cert.pem /etc/geode/key.pem # Check certificate validity openssl x509 -in /etc/geode/cert.pem -text -noout # Verify certificate not expired openssl x509 -in /etc/geode/cert.pem -noout -dates </code></pre></div>Solutions: Expired Certificate: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Generate new self-signed certificate openssl req -x509 -newkey rsa:4096 \ -keyout /etc/geode/key.pem \ -out /etc/geode/cert.pem \ -days 365 -nodes \ -subj "/CN=geode.example.com" # Restart server systemctl restart geode </code></pre></div>Permission Issues: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Fix certificate permissions sudo chown geode:geode /etc/geode/*.pem sudo chmod 600 /etc/geode/key.pem sudo chmod 644 /etc/geode/cert.pem sudo systemctl restart geode </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>Symptoms: “Maximum connections reached” or “Connection pool timeout” errors. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check active connections netstat -an | grep 3141 | wc -l # Monitor connection count over time watch -n 5 'netstat -an | grep 3141 | wc -l' </code></pre></div>Solutions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Increase max connections # Edit /etc/systemd/system/geode.service # Add: --max-connections 2000 sudo systemctl daemon-reload sudo systemctl restart geode # Or adjust client pool size # In application code, reduce pool size </code></pre></div> <h3 id="performance-issues" class="position-relative d-flex align-items-center group"> Performance 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="performance-issues" aria-haspopup="dialog" aria-label="Share link: Performance Issues"> Share link </button> </h3>Performance problems manifest as slow queries or high resource usage. <h4 id="slow-query-performance" class="position-relative d-flex align-items-center group"> Slow Query Performance <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-performance" aria-haspopup="dialog" aria-label="Share link: Slow Query Performance"> Share link </button> </h4>Symptoms: Queries take longer than expected to execute. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Profile the slow query PROFILE MATCH (p:Person)-[:KNOWS]->(friend) WHERE p.city = 'Boston' RETURN p.name, collect(friend.name); </code></pre></div>Common Causes and Solutions: Missing Index: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Check if query uses indexes EXPLAIN MATCH (p:Person) WHERE p.email = 'user@example.com' RETURN p; -- If showing full table scan, create index CREATE INDEX ON Person(email); -- Re-profile to verify improvement PROFILE MATCH (p:Person) WHERE p.email = 'user@example.com' RETURN p; </code></pre></div>Inefficient Query Structure: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Inefficient: Filter after traversal MATCH (p:Person)-[:KNOWS]->(friend) WHERE friend.city = 'Boston' RETURN p.name; -- Efficient: Filter during pattern match MATCH (p:Person)-[:KNOWS]->(friend:Person {city: 'Boston'}) RETURN p.name; </code></pre></div>Unbounded Variable-Length Paths: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Problematic: Unbounded traversal MATCH (a)-[:KNOWS*]->(b) RETURN count(*); -- Better: Limited depth MATCH (a)-[:KNOWS*1..3]->(b) RETURN count(*); </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>Symptoms: Geode process consuming excessive memory or out-of-memory errors. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check memory usage ps aux | grep geode top -p $(pidof geode) # Monitor memory over time while true; do ps -p $(pidof geode) -o %mem,rss,vsz sleep 5 done </code></pre></div>Common Causes and Solutions: Large Result Sets: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Problematic: Returns entire dataset MATCH (n:Person) RETURN n; -- Better: Paginate results MATCH (n:Person) RETURN n LIMIT 1000; </code></pre></div>Memory Leaks in Query Execution: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Restart server to reclaim memory (temporary) systemctl restart geode # Monitor for recurring memory growth # If memory grows continuously, report bug with reproduction case </code></pre></div>Insufficient System Memory: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check system memory free -h # Increase swap space (temporary measure) sudo dd if=/dev/zero of=/swapfile bs=1M count=4096 sudo mkswap /swapfile sudo swapon /swapfile # For permanent solution, add more RAM </code></pre></div> <h4 id="high-cpu-usage" class="position-relative d-flex align-items-center group"> High CPU 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-cpu-usage" aria-haspopup="dialog" aria-label="Share link: High CPU Usage"> Share link </button> </h4>Symptoms: Geode consuming excessive CPU cycles. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Identify CPU usage top -p $(pidof geode) # Profile CPU usage perf record -p $(pidof geode) -g -- sleep 10 perf report </code></pre></div>Common Causes and Solutions: Expensive Queries: Profile and optimize slow queries (see Slow Query Performance above). High Query Volume: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Monitor query rate # Review application logs for excessive query frequency # Implement caching in application layer # Add connection pooling to reduce connection overhead </code></pre></div> <h3 id="data-integrity-issues" class="position-relative d-flex align-items-center group"> Data Integrity 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="data-integrity-issues" aria-haspopup="dialog" aria-label="Share link: Data Integrity Issues"> Share link </button> </h3>Data integrity problems involve incorrect or inconsistent data. <h4 id="missing-data" class="position-relative d-flex align-items-center group"> Missing Data <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-data" aria-haspopup="dialog" aria-label="Share link: Missing Data"> Share link </button> </h4>Symptoms: Expected data not found in query results. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Verify data exists MATCH (n:Person {id: 12345}) RETURN n; -- Check for soft deletes or filters MATCH (n:Person {id: 12345, deleted: false}) RETURN n; -- Search more broadly MATCH (n) WHERE n.id = 12345 RETURN n, labels(n); </code></pre></div>Solutions: If data is genuinely missing, restore from backup: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Stop server systemctl stop geode # Restore from backup rsync -av /backup/geode-20260123/ /var/lib/geode/data/ # Start server systemctl start geode </code></pre></div> <h4 id="duplicate-data" class="position-relative d-flex align-items-center group"> Duplicate Data <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="duplicate-data" aria-haspopup="dialog" aria-label="Share link: Duplicate Data"> Share link </button> </h4>Symptoms: Multiple nodes or relationships when only one expected. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Find duplicates MATCH (n:Person) WITH n.email AS email, collect(n) AS nodes WHERE size(nodes) > 1 RETURN email, size(nodes) AS count; </code></pre></div>Solutions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Remove duplicates, keeping first MATCH (n:Person) WITH n.email AS email, collect(n) AS nodes WHERE size(nodes) > 1 FOREACH (node IN tail(nodes) | DELETE node); -- Add unique constraint to prevent future duplicates CREATE CONSTRAINT ON Person(email) ASSERT email IS UNIQUE; </code></pre></div> <h4 id="transaction-failures" class="position-relative d-flex align-items-center group"> Transaction 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="transaction-failures" aria-haspopup="dialog" aria-label="Share link: Transaction Failures"> Share link </button> </h4>Symptoms: “Transaction failed” or “Deadlock detected” errors. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check logs for transaction errors journalctl -u geode | grep -i transaction # Look for deadlock messages journalctl -u geode | grep -i deadlock </code></pre></div>Solutions: Retry Failed Transactions: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Implement retry logic in application BEGIN TRANSACTION; -- operations COMMIT; -- If fails, retry with exponential backoff </code></pre></div>Reduce Transaction Scope: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-gql" data-lang="gql">-- Break large transactions into smaller ones -- Instead of updating 10,000 nodes in one transaction: BEGIN TRANSACTION; MATCH (n:Person) WHERE n.age > 30 SET n.category = 'adult'; COMMIT; -- Do in batches: MATCH (n:Person) WHERE n.age > 30 WITH n LIMIT 1000 BEGIN TRANSACTION; SET n.category = 'adult'; COMMIT; </code></pre></div> <h3 id="build-and-installation-issues" class="position-relative d-flex align-items-center group"> Build and 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="build-and-installation-issues" aria-haspopup="dialog" aria-label="Share link: Build and Installation Issues"> Share link </button> </h3>Problems during Geode installation or compilation. <h4 id="build-failures" class="position-relative d-flex align-items-center group"> Build 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="build-failures" aria-haspopup="dialog" aria-label="Share link: Build Failures"> Share link </button> </h4>Symptoms: Compilation errors during build process. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check Zig version zig version # Should be 0.1.0 or later # Clean and rebuild make clean make build </code></pre></div>Common Causes: Wrong Zig Version: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Install correct Zig version 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" zig version </code></pre></div>Missing Dependencies: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Ubuntu/Debian sudo apt-get install build-essential # RHEL/CentOS sudo yum groupinstall "Development Tools" </code></pre></div> <h4 id="startup-failures" class="position-relative d-flex align-items-center group"> Startup 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="startup-failures" aria-haspopup="dialog" aria-label="Share link: Startup Failures"> Share link </button> </h4>Symptoms: Server fails to start or crashes immediately. Diagnostic Steps: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check systemd status systemctl status geode # View detailed logs journalctl -u geode -n 100 # Try manual startup for more verbose output /opt/geode/bin/geode serve --listen 0.0.0.0:3141 --log-level debug </code></pre></div>Common Causes: Permission Issues: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Verify data directory permissions ls -ld /var/lib/geode/data sudo chown -R geode:geode /var/lib/geode sudo chmod 750 /var/lib/geode/data </code></pre></div>Port Already in Use: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Check what's using port 3141 sudo lsof -i :3141 sudo netstat -tulpn | grep 3141 # Kill conflicting process or use different port </code></pre></div>Corrupted Data: <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Restore from backup systemctl stop geode mv /var/lib/geode/data /var/lib/geode/data.corrupted rsync -av /backup/geode-latest/ /var/lib/geode/data/ systemctl start geode </code></pre></div> <h3 id="client-specific-issues" class="position-relative d-flex align-items-center group"> Client-Specific 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="client-specific-issues" aria-haspopup="dialog" aria-label="Share link: Client-Specific Issues"> Share link </button> </h3>Problems specific to client library interactions. <h4 id="go-client-errors" class="position-relative d-flex align-items-center group"> Go Client 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="go-client-errors" aria-haspopup="dialog" aria-label="Share link: Go Client Errors"> Share link </button> </h4>Symptoms: Errors in Go applications using Geode client. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-go" data-lang="go">// Enable debug logging import "log" client.SetLogLevel("debug") // Check connection err := client.Ping(ctx) if err != nil { log.Printf("Ping failed: %v", err) } </code></pre></div> <h4 id="python-client-issues" class="position-relative d-flex align-items-center group"> Python Client 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="python-client-issues" aria-haspopup="dialog" aria-label="Share link: Python Client Issues"> Share link </button> </h4>Symptoms: Python async client errors. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"># Enable debug logging import logging logging.basicConfig(level=logging.DEBUG) # Test connection client = Client(host="localhost", port=3141) async with client.connection() as conn: await conn.query("RETURN 1 AS ok") </code></pre></div> <h4 id="rust-client-problems" class="position-relative d-flex align-items-center group"> Rust Client 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="rust-client-problems" aria-haspopup="dialog" aria-label="Share link: Rust Client Problems"> Share link </button> </h4>Symptoms: Compilation or runtime errors in Rust client. <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-rust" data-lang="rust">// Enable tracing use tracing_subscriber; tracing_subscriber::fmt::init(); // Test connection use geode_client::Client; let client = Client::from_dsn("localhost:3141")?; let mut conn = client.connect().await?; let _ = conn.query("RETURN 1 AS ok").await?; </code></pre></div> <h3 id="logging-and-diagnostics" class="position-relative d-flex align-items-center group"> Logging and 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="logging-and-diagnostics" aria-haspopup="dialog" aria-label="Share link: Logging and Diagnostics"> Share link </button> </h3>Effective use of logging aids troubleshooting. <h4 id="enabling-debug-logging" class="position-relative d-flex align-items-center group"> Enabling Debug 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="enabling-debug-logging" aria-haspopup="dialog" aria-label="Share link: Enabling Debug Logging"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Temporary debug logging geode serve --log-level debug # Permanent configuration # Edit /etc/systemd/system/geode.service # Change: --log-level info # To: --log-level debug systemctl daemon-reload systemctl restart geode </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"># Search for errors journalctl -u geode | grep -i error # Follow live logs journalctl -u geode -f # Filter by time range journalctl -u geode --since "1 hour ago" # Export logs journalctl -u geode --since today > geode-logs.txt </code></pre></div> <h4 id="common-error-messages" class="position-relative d-flex align-items-center group"> Common 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="common-error-messages" aria-haspopup="dialog" aria-label="Share link: Common Error Messages"> Share link </button> </h4>“Connection refused”: Server not running or firewall blocking “TLS handshake failed”: Certificate issues or version mismatch “Query timeout”: Query taking too long, optimize or increase timeout “Out of memory”: Insufficient system memory or memory leak “Permission denied”: File permission issues or user privileges <h3 id="prevention-strategies" class="position-relative d-flex align-items-center group"> Prevention 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="prevention-strategies" aria-haspopup="dialog" aria-label="Share link: Prevention Strategies"> Share link </button> </h3>Proactive measures prevent many common issues. <h4 id="regular-maintenance" class="position-relative d-flex align-items-center group"> Regular Maintenance <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="regular-maintenance" aria-haspopup="dialog" aria-label="Share link: Regular Maintenance"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Schedule regular backups 0 2 * * * /opt/geode/backup.sh # Monitor disk space 0 */6 * * * /opt/geode/check-disk-space.sh # Rotate logs /var/log/geode/*.log { daily rotate 7 compress delaycompress missingok notifempty } </code></pre></div> <h4 id="health-checks" class="position-relative d-flex align-items-center group"> Health Checks <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="health-checks" aria-haspopup="dialog" aria-label="Share link: Health Checks"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash">#!/bin/bash # health-check.sh # Check if server responds if ! echo "PING" | geode shell | grep -q "PONG"; then echo "Health check failed" systemctl restart geode # Send alert fi </code></pre></div> <h4 id="capacity-monitoring" class="position-relative d-flex align-items-center group"> Capacity 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="capacity-monitoring" aria-haspopup="dialog" aria-label="Share link: Capacity Monitoring"> Share link </button> </h4><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"># Monitor key metrics #!/bin/bash CONNECTIONS=$(netstat -an | grep 3141 | wc -l) MEMORY=$(ps -p $(pidof geode) -o %mem --no-headers) DISK=$(df /var/lib/geode | tail -1 | awk '{print $5}' | sed 's/%//') if [ $CONNECTIONS -gt 900 ]; then echo "Warning: Connection count high: $CONNECTIONS" fi if [ ${DISK%.*} -gt 80 ]; then echo "Warning: Disk usage high: $DISK%" fi </code></pre></div> <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>When self-troubleshooting doesn’t resolve issues. <h4 id="information-to-provide" class="position-relative d-flex align-items-center group"> Information to Provide <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="information-to-provide" aria-haspopup="dialog" aria-label="Share link: Information to Provide"> Share link </button> </h4>When seeking help, provide: <ul> <li>Geode version: <code>geode --version</code></li> <li>Operating system and version</li> <li>Complete error messages</li> <li>Steps to reproduce the issue</li> <li>Relevant log excerpts</li> <li>Configuration files (sanitized)</li> </ul> <h4 id="community-resources" class="position-relative d-flex align-items-center group"> Community Resources <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-resources" aria-haspopup="dialog" aria-label="Share link: Community Resources"> Share link </button> </h4><ul> <li>Official documentation at geodedb.com</li> <li>Issue tracker for bug reports</li> <li>Community forums for questions</li> <li>Professional support options</li> </ul> <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>Troubleshooting connects to several areas: <ul> <li>Operations - Operational procedures and management</li> <li>Monitoring - System observability and alerting</li> <li>Performance Profiling - Analyzing query performance</li> <li>Installation - Setup and deployment procedures</li> <li>Support - Getting help and resources</li> </ul> <h3 id="resources" class="position-relative d-flex align-items-center group"> Resources <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="resources" aria-haspopup="dialog" aria-label="Share link: Resources"> Share link </button> </h3>Additional troubleshooting resources: <ul> <li>Geode error code reference documentation</li> <li>Common issues and solutions knowledge base</li> <li>Diagnostic script collection</li> <li>Log analysis tools and techniques</li> </ul> Systematic troubleshooting resolves issues efficiently while building operational knowledge. Following these procedures minimizes downtime and maintains optimal Geode database health.

Popular

Related Articles

Troubleshooting Guide