apache/seatunnel · error · SensorsDataException

MISSING_NECESSARY_FIELD

MISSING_NECESSARY_FIELD

Error message

'schema' is required.

What it means

RowAccessor.getSchemaRequired() returns the configured 'schema' option but throws SensorsDataException(MISSING_NECESSARY_FIELD) if it is null or blank. The schema is mandatory for building Sensors Data records (e.g., item/item-set records need the project schema); a blank schema means the sink cannot address the correct dataset.

Source

Thrown at seatunnel-connectors-v2/connector-sensorsdata/src/main/java/org/apache/seatunnel/connectors/sensorsdata/format/record/RowAccessor.java:313

        // Set $time
        if (this.eventTimeUseCurrentTime) {
            properties.put(SensorsConst.TIME_SYSTEM_ATTR, new Date());
        } else {
            if (this.timeColumnIndex != null) {
                properties.put(
                        SensorsConst.TIME_SYSTEM_ATTR,
                        TypeUtil.toTargetType(
                                row.getField(this.timeColumnIndex),
                                SensorsDataTypes.DataTypes.DATE));
            }
        }
        return properties;
    }

    public String getSchemaRequired() {
        if (StringUtils.isBlank(schema)) {
            throw new SensorsDataException(
                    SensorsDataErrorCode.MISSING_NECESSARY_FIELD, "'schema' is required.");
        }

        return schema;
    }

    public String getDetailIdRequired(SeaTunnelRow row) {
        String detailId =
                (String)
                        TypeUtil.toTargetType(
                                row.getField(detailIdColumnIndex),
                                SensorsDataTypes.DataTypes.STRING);

        if (StringUtils.isBlank(detailId)) {
            throw new SensorsDataException(
                    SensorsDataErrorCode.MISSING_NECESSARY_FIELD, "'detailId' is required.");
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add schema = "<your_schema>" to the sink configuration and rerun the job.
2. Verify the option key spelling is exactly 'schema' and the value is non-blank (no stray whitespace-only value).
3. Validate the config before submission: fail fast if required options are blank instead of discovering this mid-job.
4. Check the connector docs for whether your record type requires schema, and set it accordingly.

Example fix

// before
sink {
  SensorsData {
    schema = ""
  }
}
// after
sink {
  SensorsData {
    schema = "default"
  }
}

// pre-flight config check
if (schema == null || schema.isBlank()) {
    throw new IllegalArgumentException("schema is required for the SensorsData sink");
}

try {
    String schema = rowAccessor.getSchemaRequired();
} catch (SensorsDataException e) {
    if (SensorsDataErrorCode.MISSING_NECESSARY_FIELD.equals(e.getErrorCode())) {
        log.error("Sink misconfigured: {}", e.getMessage());
        throw new JobConfigException("Set 'schema' in the sink config", e);
    }
    throw e;
}

When it happens

Trigger: The sink config omits schema (or sets schema = ""), and record building calls getSchemaRequired() — e.g., SpecialItemRecord building for record_type=items.

Common situations: Template configs that hardcode schema were copied without editing; schema was renamed to a wrong key so the option defaults to null; environment-specific values left as placeholder/empty strings.

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

• EVENT_NAME_NOT_SET
• UNSUPPORTED_RECORD_TYPE
• Schema config can not be empty
• Schema config need option [schema], please correct your conf
• Schema config can't contains both [fields] and [columns], pl

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