risingwavelabs/risingwave · error · iceberg::Error(ErrorKind::DataInvalid)

check if version hint exist failed: {}

Error message

check if version hint exist failed: {}

What it means

The storage-backed Iceberg catalog checks for a metadata/version-hint.text file to decide how to locate the current metadata version. If the underlying object-store existence check itself errors (network, permissions, client misconfig), it is wrapped as DataInvalid with this message.

Source

Thrown at src/connector/src/connector_common/iceberg/storage_catalog.rs:145

                if let Some(endpoint) = &config.endpoint {
                    file_io_builder = file_io_builder.with_prop(AZBLOB_ENDPOINT, endpoint)
                };
                (config.warehouse, file_io_builder.build())
            }
        };

        Ok(StorageCatalog { warehouse, file_io })
    }

    /// Check if version hint file exist.
    ///
    /// `table_path`: relative path of table dir under warehouse root.
    async fn is_version_hint_exist(&self, table_path: &str) -> Result<bool> {
        self.file_io
            .exists(format!("{table_path}/metadata/version-hint.text").as_str())
            .await
            .map_err(|err| {
                Error::new(
                    ErrorKind::DataInvalid,
                    format!("check if version hint exist failed: {}", err.as_report()),
                )
            })
    }

    /// Read version hint of table.
    ///
    /// `table_path`: relative path of table dir under warehouse root.
    async fn read_version_hint(&self, table_path: &str) -> Result<i32> {
        let content = self
            .file_io
            .new_input(format!("{table_path}/metadata/version-hint.text").as_str())?
            .read()
            .await?;
        let version_hint = String::from_utf8(content.to_vec()).map_err(|err| {
            Error::new(
                ErrorKind::DataInvalid,

View on GitHub (pinned to 6469eb736d)

Solutions

1. Read the wrapped inner error (after 'check if version hint exist failed: ') for the root cause and fix storage credentials/endpoint accordingly.
2. Verify the bucket/container exists and the endpoint/region in with-props is correct.
3. Check network connectivity/proxy settings to the object store, then retry the query.

// pre-check object-store reachability with the same credentials before running DDL
// e.g. aws s3 ls s3a://bucket/warehouse/db/table/metadata/ --region <region>

// Rust caller pattern
match catalog.load_table("db.table").await {
    Err(e) if e.to_string().contains("check if version hint exist failed") => {
        // inspect inner report, fix credentials/endpoint, then retry
    }
    other => other?,
}

When it happens

Trigger: is_version_hint_exist calls file_io.exists on <table_path>/metadata/version-hint.text; the storage backend returns an error (credentials rejected, bucket unreachable, wrong endpoint) during commit_table or load_table.

Common situations: Expired/incorrect cloud credentials; wrong region or endpoint in with-props; bucket deleted or renamed; network outage between RisingWave and the object store.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

• Fail to check exist
• Failed to check if table exists: {}
• (dataset guard acquisition error)
• disk error: {msg}
• ObjectStore failed with IO error: {0}

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