apache/seatunnel · error · OptionValidationException

'%s' must be configured when '%s' is used

Error message

'%s' must be configured when '%s' is used

What it means

RabbitmqSingleTableValidator.evaluate throws OptionValidationException saying the schema option must be configured when queue-name is used. When a single-table RabbitMQ source config supplies queue-name, a root-level schema is mandatory so the reader knows the row structure.

Source

Thrown at seatunnel-connectors-v2/connector-rabbitmq/src/main/java/org/apache/seatunnel/connectors/seatunnel/rabbitmq/config/RabbitmqSingleTableValidator.java:45

 * <p>This validator is invoked by {@code ConfigValidator} through {@code
 * Conditions.extension(QUEUE_NAME, ...)} before {@code RabbitmqSource} is constructed.
 */
public class RabbitmqSingleTableValidator implements ConditionExtension<String> {

    private static final String SCHEMA_KEY = RabbitmqBaseOptions.SCHEMA.key();
    private static final String QUEUE_NAME_KEY = RabbitmqBaseOptions.QUEUE_NAME.key();

    @Override
    public String description() {
        return "requires '" + SCHEMA_KEY + "' to be configured";
    }

    @Override
    public boolean evaluate(ReadonlyConfig config, String queueName)
            throws OptionValidationException {

        if (!config.getOptional(RabbitmqBaseOptions.SCHEMA).isPresent()) {
            throw new OptionValidationException(
                    "'%s' must be configured when '%s' is used", SCHEMA_KEY, QUEUE_NAME_KEY);
        }

        return true;
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add the required schema option at the root of the RabbitMQ source config
2. If multiple queues with different schemas are needed, switch to tables-configs and remove root-level schema/queue-name conflict (see tables-configs validator)
3. Consult the connector documentation for the exact schema syntax (SeaTunnel SeaTunnelRowType format)

Example fix

// before
source {
  RabbitMQ {
    queue-name = "orders"
  }
}
// after
source {
  RabbitMQ {
    queue-name = "orders"
    schema = {
      fields {
        id = int
        name = string
      }
    }
  }
}

ReadonlyConfig cfg = ReadonlyConfig.fromMap(jobConfig);
if (cfg.getOptional(RabbitmqBaseOptions.QUEUE_NAME).isPresent()
    && !cfg.getOptional(RabbitmqBaseOptions.SCHEMA).isPresent()) {
  throw new IllegalArgumentException("queue-name requires a root-level schema");
}

try {
  validator.evaluate(config, queueName);
} catch (OptionValidationException e) {
  System.err.println("Fix config: " + e.getMessage()); // tells you which option is missing
}

When it happens

Trigger: Config contains queue-name (or the validator is evaluated for a queue) but the root-level schema option is absent, i.e. config.getOptional(SCHEMA) is empty.

Common situations: Copy-pasted config where tables-configs examples were adapted to single-queue mode but schema was dropped; user assumed schema could be inferred; upgrading from an older connector version that had different required options.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• %s[%d]: '%s' must be configured
• Schema config can not be empty
• CONNECT_DATABASE_FAILED
• Cannot specify both '%s' and root-level '%s'.
• %s[%d]: '%s' must be configured and non-blank

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/cee93ef62fa9d375. Report an issue: GitHub.