What causes "meta client is required for Iceberg writer" in risingwavelabs/risingwave?

Run the streaming job in a real cluster so `env.meta_client()` returns a client.

meta client is required for Iceberg writer

Error message

meta client is required for Iceberg writer

What it means

The Iceberg pk-index writer requires a meta client so its `SinkWriterParam` can carry `SinkMetaClient::MetaClient` for committing/committing metadata through the meta service. `new_boxed_executor` fails with this anyhow error when `params.env.meta_client()` is `None`. This is a build-time fail-fast because the writer's commit protocol depends on meta coordination.

Source

Thrown at src/stream/src/from_proto/iceberg_with_pk_index/writer.rs:89

        let table = create_and_validate_table_impl(&config, &sink_param)
            .await
            .map_err(|e| StreamExecutorError::sink_error(e, sink_id))?;

        let pk_index_state_table = StateTableBuilder::new(
            node.get_pk_index_table()?,
            store,
            params.vnode_bitmap.clone().map(Arc::new),
        )
        .enable_preload_all_rows_by_config(&params.config)
        .with_op_consistency_level(StateTableOpConsistencyLevel::Inconsistent)
        .build()
        .await;

        let meta_client = params
            .env
            .meta_client()
            .ok_or_else(|| anyhow!("meta client is required for Iceberg writer"))?;
        let meta_client = SinkMetaClient::MetaClient(meta_client);

        let writer_param = SinkWriterParam {
            executor_id: params.executor_id,
            vnode_bitmap: params.vnode_bitmap.clone(),
            meta_client: Some(meta_client),
            extra_partition_col_idx: sink_desc.extra_partition_col_idx.map(|v| v as usize),
            actor_id: params.actor_context.id,
            sink_id,
            sink_name,
            connector: ICEBERG_SINK.to_owned(),
            streaming_config: params.config.as_ref().clone(),
            time_zone: params.actor_context.time_zone,
        };
        let writer = IcebergWriterImpl::build(&config, table, &writer_param)?;

        let exec = WriterExecutor::new(
            params.actor_context,

View on GitHub (pinned to 6469eb736d)

Solutions

Run the streaming job in a real cluster so `env.meta_client()` returns a client.
Provide a mock meta client when building the environment in tests.
Ensure the compute node startup path initializes the meta client for the executor environment.
Alternatively use a sink path that does not require meta coordination if running standalone.

Example fix

// before
let writer_param = SinkWriterParam { meta_client: None, ... };
// after
let meta_client = params.env.meta_client().ok_or_else(|| anyhow!("meta client is required for Iceberg writer"))?;
let writer_param = SinkWriterParam { meta_client: Some(SinkMetaClient::MetaClient(meta_client)), ... };

Defensive patterns

Strategy: validation

Validate before calling

// before building the writer param
assert!(params.env.meta_client().is_some(), "Iceberg writer needs meta client");

Type guard

fn require_meta_client(env: &StreamEnvironment) -> Result<MetaClientRef, anyhow::Error> {
    env.meta_client().ok_or_else(|| anyhow!("meta client is required for Iceberg writer"))
}

Try / catch

let meta_client = params.env.meta_client().ok_or_else(|| anyhow!("meta client is required for Iceberg writer"))?;

Prevention

Never construct SinkWriterParam with `meta_client: None` for Iceberg pk sinks.
Use cluster-backed environments for any integration test touching Iceberg sinks.
Fail at graph-scheduling time if the environment lacks a meta client.

When it happens

Trigger: Building the `IcebergWithPkIndexWriterExecutor` when the stream environment has no meta client — test/embedded environments, simulation runs, or compute nodes started without meta client wiring.

Common situations: Unit/integration tests constructing the executor with a test environment lacking a meta client; embedded runtime usage; a misconfigured compute node that skipped meta client initialization.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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