https://questdb.com/docs/assets/js/62d71191.c57c3a34.js

1"use strict";(self.webpackChunkdocumentation=self.webpackChunkdocumentation||[]).push([["3547"],{10558:function(e,t,r){r.r(t),r.d(t,{frontMatter:()=>s,toc:()=>l,default:()=>h,metadata:()=>n,assets:()=>c,contentTitle:()=>o});var n=JSON.parse('{"id":"troubleshooting/error-codes","title":"List of  QuestDB Error Codes","description":"A list of error codes that QuestDB may generate, with explanations and suggested actions.","source":"@site/documentation/troubleshooting/error-codes.md","sourceDirName":"troubleshooting","slug":"/troubleshooting/error-codes","permalink":"/docs/troubleshooting/error-codes","draft":false,"unlisted":false,"editUrl":"https://github.com/questdb/documentation/edit/main/documentation/troubleshooting/error-codes.md","tags":[],"version":"current","frontMatter":{"title":"List of  QuestDB Error Codes","sidebar_label":"QuestDB Error Codes","description":"A list of error codes that QuestDB may generate, with explanations and suggested actions."},"sidebar":"docs","previous":{"title":"OS Error Codes","permalink":"/docs/troubleshooting/os-error-codes"},"next":{"title":"Changelog","permalink":"/docs/changelog"}}'),i=r(85893),a=r(50065);let s={title:"List of  QuestDB Error Codes",sidebar_label:"QuestDB Error Codes",description:"A list of error codes that QuestDB may generate, with explanations and suggested actions."},o=void 0,c={},l=[{value:"Replication Errors",id:"replication-errors",level:2},{value:"ER001",id:"er001",level:3},{value:"ER002",id:"er002",level:3},{value:"ER003",id:"er003",level:3},{value:"ER004",id:"er004",level:3},{value:"ER005",id:"er005",level:3},{value:"ER006",id:"er006",level:3},{value:"ER007",id:"er007",level:3},{value:"Starting fresh with a new Data ID",id:"starting-fresh-with-a-new-data-id",level:4},{value:"Operating system error codes",id:"operating-system-error-codes",level:2}];function d(e){let t={a:"a",admonition:"admonition",code:"code",h2:"h2",h3:"h3",h4:"h4",li:"li",p:"p",pre:"pre",strong:"strong",ul:"ul",...(0,a.a)(),...e.components};return(0,i.jsxs)(i.Fragment,{children:[(0,i.jsx)(t.h2,{id:"replication-errors",children:"Replication Errors"}),"\n",(0,i.jsx)(t.p,{children:"Error codes may appear during start-up if an instance is misconfigured."}),"\n",(0,i.jsx)(t.p,{children:"When a primary instance is running, QuestDB checks that other primary instances are not running."}),"\n",(0,i.jsx)(t.p,{children:"It does so by keeping a rolling ID locally and in the object store in sync."}),"\n",(0,i.jsx)(t.p,{children:"If these two IDs are out of sync, the primary instance will raise an error."}),"\n",(0,i.jsxs)(t.p,{children:["For additional information, refer to the ",(0,i.jsx)(t.a,{href:"/docs/high-availability/overview",children:"replication overview"}),", the ",(0,i.jsx)(t.a,{href:"/docs/high-availability/setup",children:"replication setup guide"}),", and the ",(0,i.jsx)(t.a,{href:"/docs/high-availability/disaster-recovery/",children:"disaster recovery guide"}),"."]}),"\n",(0,i.jsx)(t.h3,{id:"er001",children:"ER001"}),"\n",(0,i.jsxs)(t.p,{children:["Raised at startup when a node that has just completed a\n",(0,i.jsx)(t.a,{href:"/docs/operations/point-in-time-recovery/",children:"point-in-time recovery"})," is\nconfigured with ",(0,i.jsx)(t.code,{children:"replication.role=primary"})," while its\n",(0,i.jsx)(t.code,{children:"replication.object.store"})," points at a non-empty location."]}),"\n",(0,i.jsx)(t.p,{children:'A recovered node is a new cluster, so the configured location may contain WAL data from a different replication "timeline".'}),"\n",(0,i.jsx)(t.p,{children:(0,i.jsx)(t.strong,{children:"As such, this error is raised to prevent an overwrite of the existing data."})}),"\n",(0,i.jsxs)(t.p,{children:["To resolve, shut down the database and reconfigure the ",(0,i.jsx)(t.code,{children:"replication.object.store"})," to point to a new empty location."]}),"\n",(0,i.jsx)(t.p,{children:"Once restarted, if the old location is no longer needed, you can delete it."}),"\n",(0,i.jsx)(t.h3,{id:"er002",children:"ER002"}),"\n",(0,i.jsxs)(t.p,{children:["The database cannot read or write its local copy of the replication sync ID stored in the ",(0,i.jsx)(t.code,{children:"_replication_sync_id.d"})," file."]}),"\n",(0,i.jsx)(t.p,{children:"If you recently recovered the database from a backup, check that the file permissions of the restored directory (and its contents recursively) are readable and writable."}),"\n",(0,i.jsx)(t.p,{children:'If the error indicates a "Could not read" error, perform a primary migration to recreate it.'}),"\n",(0,i.jsxs)(t.p,{children:["To do so, place an empty ",(0,i.jsx)(t.code,{children:"_migrate_primary"})," file into your databases installation directory - for example, the parent of ",(0,i.jsx)(t.code,{children:"conf"})," and ",(0,i.jsx)(t.code,{children:"db"})," directories."]}),"\n",(0,i.jsx)(t.p,{children:"This will trigger the database instance to resync with the latest state in the object store and restart as primary."}),"\n",(0,i.jsx)(t.h3,{id:"er003",children:"ER003"}),"\n",(0,i.jsx)(t.p,{children:"When you create a replica from a snapshot that is too old, this error may occur."}),"\n",(0,i.jsx)(t.p,{children:"The workflow to enable replication on the primary instance and create replicas is:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:["Reconfigure the primary instance with ",(0,i.jsx)(t.code,{children:"replication.role=primary"})," and configure its ",(0,i.jsx)(t.code,{children:"replication.object.store"})," to point to the object store and start it."]}),"\n",(0,i.jsx)(t.li,{children:"While running, snapshot the primary instance and copy the snapshot and restore it on the replica instance."}),"\n",(0,i.jsxs)(t.li,{children:["Reconfigure the replica instance with ",(0,i.jsx)(t.code,{children:"replication.role=replica"})," and ensure its ",(0,i.jsx)(t.code,{children:"replication.object.store"})," points to the same object store as the primary. Also, set a new and unique value to the ",(0,i.jsx)(t.code,{children:"cairo.snapshot.instance.id"})," configuration."]}),"\n",(0,i.jsx)(t.li,{children:"Start the replica instance."}),"\n"]}),"\n",(0,i.jsxs)(t.p,{children:["See the ",(0,i.jsx)(t.a,{href:"/docs/query/sql/checkpoint/",children:"checkpointing"})," page for more details\non how to create and restore snapshots."]}),"\n",(0,i.jsx)(t.h3,{id:"er004",children:"ER004"}),"\n",(0,i.jsx)(t.p,{children:"This error is very similar to ER003."}),"\n",(0,i.jsx)(t.p,{children:"It indicates that the transactions in the object store and the replica are out of sync."}),"\n",(0,i.jsx)(t.p,{children:"This can happen if you created the replica from a database that replicated on a different timeline or from a database unrelated to the primary instance."}),"\n",(0,i.jsx)(t.p,{children:"To resolve this, recreate the replica using a recent primary instance snapshot."}),"\n",(0,i.jsx)(t.p,{children:"Use a snapshot you created after enabling replication on the primary instance."}),"\n",(0,i.jsx)(t.p,{children:"See the workflow in ER003 for detailed steps."}),"\n",(0,i.jsx)(t.h3,{id:"er005",children:"ER005"}),"\n",(0,i.jsx)(t.p,{children:"A primary instance started which is not in sync with the configured object store."}),"\n",(0,i.jsxs)(t.p,{children:["Verify the ",(0,i.jsx)(t.code,{children:"replication.object.store"})," configuration and ensure that the object store is not in use by another primary instance."]}),"\n",(0,i.jsx)(t.p,{children:"Alternatively, you might have migrated the primary role to a different\ninstance which has committed more transactions than the current instance."}),"\n",(0,i.jsxs)(t.p,{children:["If you are certain that the ",(0,i.jsx)(t.code,{children:"replication.object.store"})," configuration is correct and that the object store is not in use by another primary instance, perform\na primary migration."]}),"\n",(0,i.jsxs)(t.p,{children:["To do so, place an empty ",(0,i.jsx)(t.code,{children:"_migrate_primary"})," file in your database installation directory, the parent of ",(0,i.jsx)(t.code,{children:"conf"})," and ",(0,i.jsx)(t.code,{children:"db"})," directories."]}),"\n",(0,i.jsx)(t.p,{children:"This will update the primary instance to the latest state from the object\nstore and have it take over as the new primary instance."}),"\n",(0,i.jsxs)(t.p,{children:["An in-place promotion with\n",(0,i.jsx)(t.a,{href:"/docs/high-availability/failover/#promote-a-replica-after-

1a-primary-loss",children:(0,i.jsx)(t.code,{children:"SWITCH ROLE TO PRIMARY"})}),"\nruns the same check before it changes anything. A replica that has not yet\napplied everything in the object store is refused: it stays a replica and\nkeeps replicating, ",(0,i.jsx)(t.code,{children:"GET /lifecycle"})," reports the ",(0,i.jsx)(t.code,{children:"replication"})," component as\n",(0,i.jsx)(t.code,{children:"DEGRADED"}),", and the reason is in the server log. Promote it again once it has\ncaught up."]}),"\n",(0,i.jsx)(t.h3,{id:"er006",children:"ER006"}),"\n",(0,i.jsx)(t.p,{children:"This error occurs when you start a primary instance and discover another instance is already acting as the primary."}),"\n",(0,i.jsx)(t.p,{children:"This typically happens after an emergency primary migration, usually due to a network partition that separated your database instances."}),"\n",(0,i.jsx)(t.p,{children:"Before proceeding, check your infrastructure to determine exactly how many primary instances are currently running."}),"\n",(0,i.jsx)(t.p,{children:"You have the following options:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsx)(t.li,{children:"Destroy the extra instance"}),"\n",(0,i.jsxs)(t.li,{children:["Reconfigure it as ",(0,i.jsx)(t.code,{children:"replication.role=replica"})," and restart it"]}),"\n",(0,i.jsx)(t.li,{children:"Perform a planned primary migration and resume the primary role on this instance"}),"\n"]}),"\n",(0,i.jsxs)(t.p,{children:["This error is also the expected outcome when a node that was demoted in place\nwith ",(0,i.jsx)(t.a,{href:"/docs/query/sql/switch-role/",children:(0,i.jsx)(t.code,{children:"SWITCH ROLE"})})," is restarted while\n",(0,i.jsx)(t.code,{children:"server.conf"})," still says ",(0,i.jsx)(t.code,{children:"replication.role=primary"}),". Set ",(0,i.jsx)(t.code,{children:"replication.role"})," to\nthe node's current role before any restart, see\n",(0,i.jsx)(t.a,{href:"/docs/high-availability/failover/#restarts",children:"Restarts"}),"."]}),"\n",(0,i.jsx)(t.h3,{id:"er007",children:"ER007"}),"\n",(0,i.jsx)(t.p,{children:"This error indicates a Data ID mismatch between the local database and the backup or replication object store."}),"\n",(0,i.jsxs)(t.p,{children:["Each QuestDB database has a unique Data ID (stored in ",(0,i.jsx)(t.code,{children:"<install_root>/db/.data_id"}),") that identifies it for backup and replication purposes. This error occurs when:"]}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsx)(t.li,{children:"Attempting to back up to an object store that contains backups from a different database instance"}),"\n",(0,i.jsx)(t.li,{children:"A replication object store contains data from a different primary instance"}),"\n"]}),"\n",(0,i.jsx)(t.p,{children:"To resolve:"}),"\n",(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"For backup creation"}),": Verify the ",(0,i.jsx)(t.code,{children:"backup.object.store"})," points to the correct location for this database instance. If intentionally backing up to a new location, the location must be empty."]}),"\n",(0,i.jsxs)(t.li,{children:[(0,i.jsx)(t.strong,{children:"For replication"}),": Verify the ",(0,i.jsx)(t.code,{children:"replication.object.store"})," configuration matches the primary instance that owns the data."]}),"\n"]}),"\n",(0,i.jsx)(t.p,{children:'Note: Restore operations check for an empty database separately. If the target\ndatabase already has a Data ID, restore fails with: "The local database is not\nempty. It already has an associated data ID."'}),"\n",(0,i.jsx)(t.h4,{id:"starting-fresh-with-a-new-data-id",children:"Starting fresh with a new Data ID"}),"\n",(0,i.jsx)(t.p,{children:"A Data ID is automatically generated when QuestDB first starts with an empty\ndatabase. To intentionally start fresh:"}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Recommended"}),": Create a new, empty database directory and configure QuestDB\nto use it."]}),"\n",(0,i.jsxs)(t.p,{children:[(0,i.jsx)(t.strong,{children:"Alternative"}),": Delete the existing ",(0,i.jsx)(t.code,{children:".data_id"})," file (stop QuestDB first):"]}),"\n",(0,i.jsx)(t.pre,{children:(0,i.jsx)(t.code,{className:"language-bash",children:"# Stop QuestDB first!\nrm <install_root>/db/.data_id\n# Restart QuestDB - a new Data ID will be generated\n"})}),"\n",(0,i.jsxs)(t.admonition,{type:"warning",children:[(0,i.jsx)(t.p,{children:"Changing the Data ID on a database with existing data will:"}),(0,i.jsxs)(t.ul,{children:["\n",(0,i.jsx)(t.li,{children:"Break any existing replication configuration"}),"\n",(0,i.jsx)(t.li,{children:"Make existing backups incompatible for restore"}),"\n",(0,i.jsx)(t.li,{children:"Cause ER007 errors when connecting to the original object store"}),"\n"]})]}),"\n",(0,i.jsxs)(t.p,{children:["See the ",(0,i.jsx)(t.a,{href:"/docs/operations/backup/",children:"Backup and Restore guide"})," for more information."]}),"\n",(0,i.jsx)(t.h2,{id:"operating-system-error-codes",children:"Operating system error codes"}),"\n",(0,i.jsxs)(t.p,{children:["Refer to the ",(0,i.jsx)(t.a,{href:"/docs/troubleshooting/os-error-codes/",children:"OS error codes"})," page for any\nfile or network related errors that QuestDB may raise."]})]})}function h(e={}){let{wrapper:t}={...(0,a.a)(),...e.components};return t?(0,i.jsx)(t,{...e,children:(0,i.jsx)(d,{...e})}):d(e)}},50065:function(e,t,r){r.d(t,{Z:()=>o,a:()=>s});var n=r(67294);let i={},a=n.createContext(i);function s(e){let t=n.useContext(a);return n.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function o(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(i):e.components||i:s(e.components),n.createElement(a.Provider,{value:t},e.children)}}}]);