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

no version hint found for table

Error message

no version hint found for table

What it means

During commit_table, the storage catalog only writes a new metadata version if a `version-hint.text` file already exists for the table. If it does not exist, the catalog refuses to commit because it cannot determine the current version, treating the table as unknown or uninitialized in this catalog.

Source

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

    pub fn file_io(&self) -> &FileIO {
        &self.file_io
    }

    fn table_path(&self, table: &TableIdent) -> String {
        let mut names = table.namespace.clone().inner();
        names.push(table.name.clone());
        if self.warehouse.ends_with('/') {
            format!("{}{}", self.warehouse, names.join("/"))
        } else {
            format!("{}/{}", self.warehouse, names.join("/"))
        }
    }

    async fn commit_table(&self, table_path: &str, next_metadata: TableMetadata) -> Result<()> {
        let current_version = if self.is_version_hint_exist(table_path).await? {
            self.read_version_hint(table_path).await?
        } else {
            return Err(Error::new(
                ErrorKind::DataInvalid,
                "no version hint found for table",
            ));
        };

        // # NOTE
        // Iceberg rust didn't support rename operation now, so this commit operation is not atomic.
        let final_metadata_file_path = format!(
            "{table_path}/metadata/v{}.metadata.json",
            current_version + 1
        );
        self.file_io()
            .new_output(final_metadata_file_path)?
            .write(serde_json::to_string(&next_metadata)?.into())
            .await?;

        // write version hint
        let final_file_path = format!("{table_path}/metadata/version-hint.text");

View on GitHub (pinned to 6469eb736d)

Solutions

1. Verify `{table_path}/metadata/version-hint.text` exists and is readable with your storage credentials; fix the table path if it was mistyped.
2. If the table is managed by another catalog, configure that catalog (Hive/REST/Glue) instead of the storage catalog.
3. If the hint file was deleted, recreate it containing the highest existing `v<N>.metadata.json` version number.
4. Check object-store lifecycle/retention rules and exclude the `metadata/` prefix from expiration.

Example fix

// before: storage catalog pointed at an external-catalog-managed table
// after: use the proper catalog config
catalog.type = "rest" // or "hive", matching how the table was created

let hint_path = format!("{table_path}/metadata/version-hint.text");
if !file_io.exists(&hint_path).await? {
    return Err(format!("{hint_path} missing; use the catalog that manages this table or recreate the hint"));
}

// catch and route to the right catalog
match catalog.commit_table(path, metadata).await {
    Err(e) if e.to_string().contains("no version hint found") => {
        return Err(anyhow!("table is not managed by the storage catalog; use Hive/REST/Glue"));
    }
    other => other,
}

When it happens

Trigger: Calling update_table on a table whose `{table_path}/metadata/version-hint.text` is missing — e.g. the table was created by another catalog (Hive/REST/Nessie), the metadata folder was deleted, or the table path is wrong.

Common situations: Pointing RisingWave at a table managed by an external Iceberg catalog; version-hint file removed by a retention/lifecycle rule on the object store; typo in the table identifier/path; table registered in metadata but never committed via the storage catalog.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• parse version hint failed
• `catalog.type` must be set
• Failed to list iceberg namespaces.
• Failed to load iceberg table.
• Failed to drop iceberg table.

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