risingwavelabs/risingwave · error · SinkError::Config

license feature check failed (ClickHouseSharedEngine not ava

Error message

license feature check failed (ClickHouseSharedEngine not available): wrapped error from risingwave_common::license::Feature::check_available

What it means

If the sink targets a ClickHouse SharedMergeTree (shared tree) engine, RisingWave checks that the ClickHouseSharedEngine license feature is available via risingwave_common::license::Feature::check_available. Without an appropriate enterprise license the check fails and validation aborts with this error.

Source

Thrown at src/connector/src/sink/clickhouse.rs:581

    crate::impl_validate_sink_unknown_fields!();

    async fn validate(&self) -> Result<()> {
        // For upsert clickhouse sink, the primary key must be defined.
        if !self.is_append_only && self.pk_indices.is_empty() {
            return Err(SinkError::Config(anyhow!(
                "Primary key not defined for upsert clickhouse sink (please define in `primary_key` field)"
            )));
        }

        // check reachability
        let client = self.config.common.build_client()?;

        let (clickhouse_column, clickhouse_engine) =
            query_column_engine_from_ck(client, &self.config).await?;
        if clickhouse_engine.is_shared_tree() {
            risingwave_common::license::Feature::ClickHouseSharedEngine
                .check_available()
                .map_err(|e| anyhow::anyhow!(e))?;
        }

        if !self.is_append_only
            && !clickhouse_engine.is_collapsing_engine()
            && !clickhouse_engine.is_delete_replacing_engine()
        {
            return match clickhouse_engine {
                ClickHouseEngine::ReplicatedReplacingMergeTree(None) | ClickHouseEngine::ReplacingMergeTree(None) | ClickHouseEngine::SharedReplacingMergeTree(None) =>  {
                    Err(SinkError::ClickHouse("To enable upsert with a `ReplacingMergeTree`, you must set a `clickhouse.delete.column` to the UInt8 column in ClickHouse used to signify deletes. See https://clickhouse.com/docs/en/engines/table-engines/mergetree-family/replacingmergetree#is_deleted for more information".to_owned()))
                }
                _ => Err(SinkError::ClickHouse("If you want to use upsert, please use either `VersionedCollapsingMergeTree`, `CollapsingMergeTree` or the `ReplacingMergeTree` in ClickHouse".to_owned()))
            };
        }

        self.check_column_name_and_type(&clickhouse_column)?;
        if !self.is_append_only {
            self.check_pk_match(&clickhouse_column)?;
        }

View on GitHub (pinned to 6469eb736d)

Solutions

Obtain/install a RisingWave enterprise license that enables the ClickHouseSharedEngine feature.
Switch the ClickHouse table to a non-shared engine (e.g. MergeTree, CollapsingMergeTree).
If the license should cover this, verify license activation and feature availability before creating the sink.

Example fix

// before
-- target table uses SharedMergeTree with no enterprise license
CREATE TABLE t (...) ENGINE = SharedMergeTree ...;
// after
CREATE TABLE t (...) ENGINE = MergeTree ORDER BY id; -- non-shared engine, no license needed

Defensive patterns

Strategy: try-catch

Validate before calling

if (clickhouseEngine === 'SharedMergeTree' && !license.features.includes('ClickHouseSharedEngine')) {
  throw new Error('ClickHouseSharedEngine license feature not available; use a non-shared engine or obtain a license');
}

Try / catch

try {
  await createSink(clickHouseSinkOptions);
} catch (e) {
  if (String(e.message).includes('ClickHouseSharedEngine not available')) {
    // fall back to a non-shared MergeTree table or activate the enterprise license
  } else throw e;
}

Prevention

Confirm license feature availability before targeting shared-tree engines.
Use standard MergeTree/CollapsingMergeTree engines when licensing is uncertain.
Monitor license expiry in enterprise deployments that rely on ClickHouse shared engines.

When it happens

Trigger: ClickHouse sink whose target table uses a SharedTree engine (e.g. SharedMergeTree on ClickHouse Cloud) while the RisingWave deployment lacks a license enabling ClickHouseSharedEngine.

Common situations: Enterprise/Cloud feature used with an open-source or unlicensed deployment; expired or missing license covering the ClickHouse shared-engine integration.

Related errors

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