risingwavelabs/risingwave · error · SinkError

File sink can only be created with sink_decouple enabled. Pl

Error message

File sink can only be created with sink_decouple enabled. Please run `set sink_decouple = true` first.

What it means

File sinks buffer data and commit files only when the batching strategy is met, so they require decoupled sinks (checkpoint-driven commits on a durable log store). This function is a hard override for the `is_sink_decouple` trait hook: it forces decoupling on by default but explicitly rejects a user who sets `sink_decouple = false`, because without decoupling an untruncated barrier would block checkpoints forever on the in-memory log store.

Source

Thrown at src/connector/src/sink/file_sink/opendal_sink.rs:140

    Webhdfs,
    Snowflake,
}

impl<S: OpendalSinkBackend> Sink for FileSink<S> {
    type LogSinker = BatchingLogSinker<OpenDalSinkWriter>;

    const SINK_NAME: &'static str = S::SINK_NAME;

    fn validate_unknown_fields(&self) -> Result<()> {
        crate::sink::validate_sink_unknown_fields(&self.unknown_fields)
    }

    /// A file is committed only once the batching strategy is met, so an untruncated barrier
    /// would block the checkpoint forever on the non-decoupled in-memory log store.
    fn is_sink_decouple(user_specified: &SinkDecouple) -> Result<bool> {
        match user_specified {
            SinkDecouple::Default | SinkDecouple::Enable => Ok(true),
            SinkDecouple::Disable => Err(SinkError::Config(anyhow!(
                "File sink can only be created with sink_decouple enabled. Please run `set sink_decouple = true` first."
            ))),
        }
    }

    async fn validate(&self) -> Result<()> {
        if matches!(self.engine_type, EngineType::Snowflake) {
            risingwave_common::license::Feature::SnowflakeSink
                .check_available()
                .map_err(|e| anyhow::anyhow!(e))?;
        }
        if !self.is_append_only {
            return Err(SinkError::Config(anyhow!(
                "File sink only supports append-only mode at present. \
                    Please change the query to append-only, and specify it \
                    explicitly after the `FORMAT ... ENCODE ...` statement. \
                    For example, `FORMAT xxx ENCODE xxx(force_append_only='true')`"
            )));

View on GitHub (pinned to 6469eb736d)

Solutions

Remove the `sink_decouple = false` setting or set `sink_decouple = true` before creating the sink
Run `SET sink_decouple = true;` in the session, or reset it to default so the file sink override applies
Create the sink in a fresh session that does not carry a disabled sink_decouple setting

Example fix

// before
SET sink_decouple = false;
CREATE SINK s FROM mv WITH (connector = 's3', ...);
// after
SET sink_decouple = true;
CREATE SINK s FROM mv WITH (connector = 's3', ...);

Defensive patterns

Strategy: validation

Validate before calling

-- run before CREATE SINK
SHOW sink_decouple;
-- ensure it is not 'false'; if needed:
SET sink_decouple = true;

Try / catch

match err {
    SinkError::Config(msg) if msg.contains("sink_decouple") => {
        // re-create the sink with sink_decouple = true
    }
    other => return Err(other),
}

Prevention

Do not set sink_decouple = false globally or in sessions used for file sinks
Use default settings for file sinks — decoupling is forced and recommended
Add a comment to shared SQL scripts noting file sinks require sink_decouple

When it happens

Trigger: Creating a file sink (S3/GCS/Azure/FS opendal-based) with the WITH/SESSION option `sink_decouple = false` (or explicitly disabled), e.g. `CREATE SINK ... WITH (...) sink_decouple = false` or `SET sink_decouple = false` at session level.

Common situations: Users who disabled sink_decouple globally to test or debug other sinks, then create a file sink; copied session settings from a non-file sink setup; older workflows predating the decouple requirement.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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