risingwavelabs/risingwave · error · SchedulerError

Pin snapshot error: {0} fails to get epoch {1}

Error message

Pin snapshot error: {0} fails to get epoch {1}

What it means

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.

Source

Thrown at src/frontend/src/scheduler/error.rs:26

//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

use risingwave_batch::error::BatchError;
use risingwave_common::session_config::QueryMode;
use risingwave_connector::error::ConnectorError;
use risingwave_rpc_client::error::RpcError;
use thiserror::Error;

use crate::error::{ErrorCode, RwError};
use crate::scheduler::plan_fragmenter::QueryId;

#[derive(Error, Debug)]
pub enum SchedulerError {
    #[error("Pin snapshot error: {0} fails to get epoch {1}")]
    PinSnapshot(QueryId, u64),

    #[error(transparent)]
    RpcError(
        #[from]
        #[backtrace]
        RpcError,
    ),

    #[error("{0}")]
    TaskExecutionError(String),

    #[error("Task got killed because compute node running out of memory")]
    TaskRunningOutOfMemory,

    /// Used when receive cancel request for some reason, such as user cancel or timeout.
    #[error("Query cancelled: {0}")]
    QueryCancelled(String),

View on GitHub (pinned to 6469eb736d)

Solutions

1. 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.
2. Retry the query — a transient meta RPC failure or election typically resolves in seconds.
3. If using explicit epoch-based queries, use a current epoch or drop the pinned-epoch option.
4. Verify network connectivity between the frontend node and meta node on the meta RPC port.

Example fix

// application-side retry
for attempt in 0..3 {
    match run_query(client, sql) {
        Ok(rows) => return Ok(rows),
        Err(e) if e.to_string().contains("Pin snapshot error") && attempt < 2 => {
            tokio::time::sleep(Duration::from_secs(2)).await;
        }
        Err(e) => return Err(e),
    }
}

-- check cluster health before running queries
SELECT * FROM rw_catalog.rw_actors; -- or SHOW LIVE NODES / meta health endpoint

// app-side: catch and retry transient pin failures
match err.to_string().contains("Pin snapshot error") { true => retry_with_backoff(), false => return Err(err) }

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Request timed out: what client-side request timeouts mean across libraries (Request timed out, TIMED_OUT, APITimeoutError) — this error's family across 39 libraries.

Related errors

• table id {table_id} may have been dropped
• RpcError
• {0}
• Task got killed because compute node running out of memory
• Query cancelled: {0}

AI-assisted analysis of risingwavelabs/risingwave@6469eb736d (2026-09-11). Data as JSON: /api/errors/634edc15de908167. Report an issue: GitHub.