ALTER STREAMING ENABLE UNALIGNED JOIN is only supported in…

Error message

ALTER STREAMING ENABLE UNALIGNED JOIN is only supported in debug mode

What it means

The unaligned-join toggle is a debugging/testing-only feature guarded by cfg!(debug_assertions). In release builds of RisingWave the handler short-circuits and bails unconditionally, because the feature is not considered production-safe. This is a build-mode restriction, not a SQL or permission problem.

Solutions

Build RisingWave from source in debug mode (./risedev build or cargo build without --release) and run the statement against that instance.
Do not use unaligned join in production; restructure the query or accept aligned join behavior instead.
If you only need the log-store alignment semantics, use supported production configuration options rather than this debug toggle.

Example fix

// before (release binary)
cargo build --release && ./risedev d  # then: ALTER STREAMING ENABLE UNALIGNED JOIN mv;
// after (debug binary)
cargo build && ./risedev d  # then: ALTER STREAMING ENABLE UNALIGNED JOIN mv;

Defensive patterns

Strategy: try-catch

Try / catch

try {
    await client.query('ALTER STREAMING ENABLE UNALIGNED JOIN my_mv');
} catch (e) {
    if (e.message.includes('only supported in debug mode')) {
        // running a release build: skip or restructure the query instead
    } else {
        throw e;
    }
}

Prevention

Never rely on unaligned join in production code paths; it is debug-only.
Gate any debug-only SQL in tooling behind a build-mode check (cfg!(debug_assertions) equivalent / version string).
Treat this error as a signal to redesign the query rather than to retry.

When it happens

Trigger: Executing `ALTER STREAMING ENABLE/DISABLE UNALIGNED JOIN ...` against a RisingWave binary compiled in release mode (cargo build --release, official release packages, most production deployments).

Common situations: Developer reads about the unaligned-join debug knob and tries it on a production/release cluster; CI or staging runs a release artifact while the docs were written for a locally built debug binary.

Related errors

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

Appendix: source

Thrown at src/frontend/src/handler/alter_streaming_enable_unaligned_join.rs:80

                        // Other relation types (Subquery, Join, etc.) are not directly describable.
                        return Err(not_found_err.into());
                    }
                }
            } else if let Ok(sink) = binder.bind_sink_by_name(name.clone()) {
                sink.sink_catalog.id.as_job_id()
            } else {
                return Err(not_found_err.into());
            }
        };
        let meta_client = session.env().meta_client();
        meta_client
            .set_sync_log_store_aligned(job_id, !enable)
            .await?;
        Ok(PgResponse::empty_result(
            StatementType::ALTER_MATERIALIZED_VIEW,
        ))
    } else {
        bail!("ALTER STREAMING ENABLE UNALIGNED JOIN is only supported in debug mode");
    }
}

View on GitHub (pinned to 6469eb736d)