apache/beam · error · IllegalArgumentException

shardsNumber must be greater than 0.

Error message

shardsNumber must be greater than 0.

What it means

validate() in SnowflakeWriteConfiguration rejects a shardsNumber that is set but not strictly positive. shardsNumber sets the number of parallel insert shards for streaming (SnowPipe) writes; zero or negative values cannot describe a shard count. The check fires only when the value is explicitly configured.

Solutions

1. Set shardsNumber to a positive integer (e.g. 2-8 depending on throughput) or leave it unset to use the default.
2. Fix the source of the computed value so unset parallelism yields null, not 0.
3. Only call withShardsNumber when the computed shard count is > 0.

Example fix

// before
.withShardsNumber(0)
// after
.withShardsNumber(4)

Integer shardsNumber = cfg.getShardsNumber();
if (shardsNumber != null && shardsNumber <= 0) {
  throw new IllegalArgumentException("shardsNumber must be > 0 or null");
}

try {
  config.validate();
} catch (IllegalArgumentException e) {
  if (e.getMessage().startsWith("shardsNumber")) { /* set a positive shard count, e.g. 4 */ }
  throw e;
}

When it happens

Trigger: Setting shardsNumber to 0 or a negative integer (e.g. .withShardsNumber(0)) on SnowflakeWriteConfiguration before pipeline validation.

Common situations: Shard count computed from a parallelism setting that defaults to 0, or a copied config where the field was left as 0 placeholder.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• flushRowLimit must be greater than 0.
• flushTimeLimitMillis must be greater than 0.
• snowPipe is required for streaming writes.
• Either table or query must be specified.
• Failed to setLoginTimeout

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/2b026eb6fe636c9c. Report an issue: GitHub.

Appendix: source

Thrown at sdks/java/io/snowflake/src/main/java/org/apache/beam/sdk/io/snowflake/SnowflakeWriteConfiguration.java:170

    String debugMode = getDebugMode();
    if (debugMode != null) {
      parseStreamingLogLevel(debugMode);
    }

    Integer flushRowLimit = getFlushRowLimit();
    if (flushRowLimit != null && flushRowLimit <= 0) {
      throw new IllegalArgumentException("flushRowLimit must be greater than 0.");
    }

    Long flushTimeLimitMillis = getFlushTimeLimitMillis();
    if (flushTimeLimitMillis != null && flushTimeLimitMillis <= 0) {
      throw new IllegalArgumentException("flushTimeLimitMillis must be greater than 0.");
    }

    Integer shardsNumber = getShardsNumber();
    if (shardsNumber != null && shardsNumber <= 0) {
      throw new IllegalArgumentException("shardsNumber must be greater than 0.");
    }
  }

  private static void requireNonEmpty(String value, String name) {
    if (value == null || value.isEmpty()) {
      throw new IllegalArgumentException(name + " cannot be empty");
    }
  }

  @AutoValue.Builder
  public abstract static class Builder {

    public abstract Builder setServerName(String value);

    public abstract Builder setUsername(@Nullable String value);

    public abstract Builder setPassword(@Nullable String value);

View on GitHub (pinned to 12126d8942)