databendlabs/databend · error · Unsupported

unsupported iceberg scheme

Error message

unsupported iceberg scheme: {}

What it means

IcebergFileIO maps the FileIO scheme string to an opendal::Scheme for a fixed set: s3/s3a, gs/gcs, oss, abfs/abfss/wasb/wasbs, file, memory. Any other scheme found in the iceberg FileIO is rejected as ErrorKind::Unsupported, because this wrapper has no operator builder for it.

Solutions

  1. Change the table/location storage to one of the supported schemes: s3/s3a, gs/gcs, oss, abfs/abfss/wasb/wasbs, file, memory.
  2. If the backend is genuinely needed, extend the match in src/common/storage/src/operator.rs:881 to map the new scheme to an opendal::Scheme.
  3. Check the scheme string for typos (e.g. 'S3' vs 's3') and ensure the iceberg FileIO was built with the intended scheme.

Example fix

// before
let file_io = FileIO::Builder::new().build("hdfs://namenode/warehouse")?;
// after
let file_io = FileIO::Builder::new().build("s3://my-bucket/warehouse")?;
Defensive patterns

Strategy: try-catch

Validate before calling

const SUPPORTED: &[&str] = &["s3", "s3a", "gs", "gcs", "oss", "abfs", "abfss", "wasb", "wasbs", "file", "", "memory"];
if !SUPPORTED.contains(&file_io_scheme.as_str()) {
    return Err(anyhow!("iceberg scheme {file_io_scheme:?} is not supported"));
}

Try / catch

match file_io.get_operator_path(location) {
    Err(e) if e.message().starts_with("unsupported iceberg scheme") => {
        // fall back to a supported backend or surface a clear user error
        bail!("backend not supported; use s3/gcs/oss/adls/file storage");
    }
    other => other,
}

Prevention

When it happens

Trigger: build_operator encountering self.scheme outside the supported list, e.g. a FileIO constructed for 'oss' with an unhandled alias, a custom/unknown scheme like 'webhdfs' or 'hdfs', or a corrupted/empty scheme value not matching any arm.

Common situations: Using an iceberg catalog whose FileIO was configured for a backend this integration does not support (e.g. HDFS); typos in scheme configuration; a new iceberg-rs scheme added upstream before Databend added support.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

AI-assisted analysis of databendlabs/databend@288d84d76e (2026-09-11). Data as JSON: /api/errors/70c8b2ccff40fb4b. Report an issue: GitHub.

Appendix: source

Thrown at src/common/storage/src/operator.rs:889

                    opendal_config.insert(key.clone(), value.clone());
                    None
                }
            };

            if let Some(opendal_key) = opendal_key {
                opendal_config.insert(opendal_key.to_string(), value.clone());
            }
        }

        let opendal_scheme = match self.scheme.as_str() {
            "s3" | "s3a" => opendal::Scheme::S3,
            "gs" | "gcs" => opendal::Scheme::Gcs,
            "oss" => opendal::Scheme::Oss,
            "abfs" | "abfss" | "wasb" | "wasbs" => opendal::Scheme::Azdls,
            "file" | "" => opendal::Scheme::Fs,
            "memory" => opendal::Scheme::Memory,
            _ => {
                return Err(Error::new(
                    ErrorKind::Unsupported,
                    format!("unsupported iceberg scheme: {}", self.scheme),
                ));
            }
        };

        let op = Operator::via_iter(opendal_scheme, opendal_config)
            .map_err(|e| Error::other(e.to_string()))?;

        Ok((op, relative_path_pos))
    }
}

impl OperatorRegistry for IcebergFileIO {
    fn get_operator_path<'a>(&self, location: &'a str) -> Result<(Operator, &'a str)> {
        let (op, pos) = self.build_operator(location)?;
        Ok((op, &location[pos..]))
    }

View on GitHub (pinned to 288d84d76e)