apache/druid · error · IllegalArgumentException

Disallowed column names

Error message

Disallowed column names[%s]

What it means

FrameReader.create validates the RowSignature that will be used to interpret frames. Column names that are disallowed (e.g. containing characters or values that conflict with frame storage rules, as found by FrameWriterUtils.findDisallowedFieldNames) are rejected on read even though they should have been caught on write. IAE indicates the caller supplied an invalid signature.

Solutions

1. Sanitize or rename offending columns in the RowSignature before creating the FrameReader
2. Validate with FrameWriterUtils.findDisallowedFieldNames(signature) before calling create and fix the listed names
3. Fix the upstream writer/ingestion spec that produced the bad column names

Example fix

// before
FrameReader reader = FrameReader.create(signature); // signature has "a.b" column
// after
Set<String> bad = FrameWriterUtils.findDisallowedFieldNames(signature);
if (!bad.isEmpty()) {
  signature = renameColumns(signature, bad);
}
FrameReader reader = FrameReader.create(signature);

Set<String> bad = FrameWriterUtils.findDisallowedFieldNames(signature); if (!bad.isEmpty()) { throw new IllegalArgumentException("Bad column names: " + bad); }

null

try { FrameReader.create(signature); } catch (IllegalArgumentException e) { /* rename offending columns and retry */ }

When it happens

Trigger: Calling FrameReader.create(RowSignature) with a signature containing a column name like an empty string, or one containing dots/other disallowed characters per FrameWriterUtils.findDisallowedFieldNames.

Common situations: Programmatically building RowSignature with raw column names from user input or external schemas; joining/ad-hoc queries producing synthetic columns with illegal names.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• A local input source accepts only one of
• A local input source can set parameter
• A local input source requires one parameter of
• A local input source requires one property of
• A table definition must include a table spec.

AI-assisted analysis of apache/druid@9b90983fd2 (2026-09-07). Data as JSON: /api/errors/8a905e704fe08dc2. Report an issue: GitHub.

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/frame/read/FrameReader.java:86

  private FrameReader(final RowSignature signature)
  {
    this.signature = signature;
  }

  /**
   * Create a reader for frames with a given {@link RowSignature}. The signature must exactly match the frames to be
   * read, or else behavior is undefined.
   *
   * @param signature signature used to generate the reader
   */
  public static FrameReader create(final RowSignature signature)
  {
    // Double-check that the frame does not have any disallowed field names. Generally, we expect this to be
    // caught on the write side, but we do it again here for safety.
    final Set<String> disallowedFieldNames = FrameWriterUtils.findDisallowedFieldNames(signature);
    if (!disallowedFieldNames.isEmpty()) {
      throw new IAE("Disallowed column names[%s]", disallowedFieldNames);
    }

    // Check that the signature does not have any null types.
    for (int columnNumber = 0; columnNumber < signature.size(); columnNumber++) {
      if (!signature.getColumnType(columnNumber).isPresent()) {
        throw DruidException.defensive("Missing type for column[%s]", signature.getColumnName(columnNumber));
      }
    }

    return new FrameReader(signature);
  }

  public RowSignature signature()
  {
    return signature;
  }

  /**

View on GitHub (pinned to 9b90983fd2)