{"record":{"id":"634edc15de908167","repo":"risingwavelabs/risingwave","slug":"pin-snapshot-error-0-fails-to-get-epoch-1","errorCode":null,"errorMessage":"Pin snapshot error: {0} fails to get epoch {1}","messagePattern":"Pin snapshot error: (.+?) fails to get epoch (.+?)","errorType":"exception","errorClass":"SchedulerError","httpStatus":null,"severity":"error","filePath":"src/frontend/src/scheduler/error.rs","lineNumber":26,"sourceCode":"//\n// Unless required by applicable law or agreed to in writing, software\n// distributed under the License is distributed on an \"AS IS\" BASIS,\n// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n// See the License for the specific language governing permissions and\n// limitations under the License.\n\nuse risingwave_batch::error::BatchError;\nuse risingwave_common::session_config::QueryMode;\nuse risingwave_connector::error::ConnectorError;\nuse risingwave_rpc_client::error::RpcError;\nuse thiserror::Error;\n\nuse crate::error::{ErrorCode, RwError};\nuse crate::scheduler::plan_fragmenter::QueryId;\n\n#[derive(Error, Debug)]\npub enum SchedulerError {\n    #[error(\"Pin snapshot error: {0} fails to get epoch {1}\")]\n    PinSnapshot(QueryId, u64),\n\n    #[error(transparent)]\n    RpcError(\n        #[from]\n        #[backtrace]\n        RpcError,\n    ),\n\n    #[error(\"{0}\")]\n    TaskExecutionError(String),\n\n    #[error(\"Task got killed because compute node running out of memory\")]\n    TaskRunningOutOfMemory,\n\n    /// Used when receive cancel request for some reason, such as user cancel or timeout.\n    #[error(\"Query cancelled: {0}\")]\n    QueryCancelled(String),","sourceCodeStart":8,"sourceCodeEnd":44,"githubUrl":"https://github.com/risingwavelabs/risingwave/blob/6469eb736d691e8e9b8a419a57edd6429ca77417/src/frontend/src/scheduler/error.rs#L8-L44","documentation":"SchedulerError::PinSnapshot is raised by the batch query scheduler when it tries to pin a consistency snapshot epoch from the meta service for a query and fails. The message carries the QueryId and the epoch it attempted. Without a pinned epoch the query cannot read a consistent snapshot of the materialized data and is aborted.","triggerScenarios":"Issuing a batch query (SELECT against materialized views/tables) where `pin_snapshot` RPC to the meta node fails — meta node unreachable/restarting, or the requested epoch (e.g. from a time-travel/query-version context) is no longer available.","commonSituations":"Meta node down or under heavy load during query submission; cluster leadership changes; querying with an old consistency context (e.g. `SET` query epoch) whose epoch has been GCed.","solutions":["Check meta node health (`ps` / logs of meta node, `SELECT * FROM rw_catalog.rw_meta_snapshot` style diagnostics) and retry the query once the meta node is reachable.","Retry the query — a transient meta RPC failure or election typically resolves in seconds.","If using explicit epoch-based queries, use a current epoch or drop the pinned-epoch option.","Verify network connectivity between the frontend node and meta node on the meta RPC port."],"exampleFix":"// application-side retry\nfor attempt in 0..3 {\n    match run_query(client, sql) {\n        Ok(rows) => return Ok(rows),\n        Err(e) if e.to_string().contains(\"Pin snapshot error\") && attempt < 2 => {\n            tokio::time::sleep(Duration::from_secs(2)).await;\n        }\n        Err(e) => return Err(e),\n    }\n}","handlingStrategy":"retry","validationCode":"-- check cluster health before running queries\nSELECT * FROM rw_catalog.rw_actors; -- or SHOW LIVE NODES / meta health endpoint","typeGuard":null,"tryCatchPattern":"// app-side: catch and retry transient pin failures\nmatch err.to_string().contains(\"Pin snapshot error\") { true => retry_with_backoff(), false => return Err(err) }","preventionTips":["Monitor meta node liveness before issuing batch queries","Use bounded retries with backoff for query submission","Avoid pinned-epoch queries referencing very old epochs"],"tags":["frontend","scheduler","meta","epoch","snapshot"],"backgroundTag":"request-timeout","analyzedSha":"6469eb736d691e8e9b8a419a57edd6429ca77417","analyzedAt":"2026-09-11T21:06:21.487Z","contentChangedAt":"2026-09-11T21:06:21.487Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}