apache/druid · error · IllegalArgumentException

Cannot have a comma in the name of a file, got

Error message

Cannot have a comma in the name of a file, got[%s].

What it means

SegmentFileBuilderV10 uses commas internally to delimit file names inside a container file, so a name containing ',' is rejected with this IllegalArgumentException in addWithChannel. This keeps the container manifest unambiguous. Callers must use comma-free internal file names (e.g. column and index file names).

Solutions

1. Sanitize or encode the file name to remove commas before calling addWithChannel (e.g. replace ',' with an escape sequence)
2. Use Druid's FileNameUtils/StringUtils encode helper or a URL-encoding step for names derived from data
3. Reject the bad name earlier at ingestion time with a clear validation error so it never reaches the builder

Example fix

// before
builder.addWithChannel(columnName + ".v1", size);
// after
String safeName = columnName.replace(",", "_%2C_");
builder.addWithChannel(safeName + ".v1", size);

// Java: reject comma-containing names before calling the builder
if (name.contains(",")) { throw new IllegalArgumentException("comma in name: " + name); }

String sanitizeFileName(String name) {
  return name.contains(",") ? name.replace(",", "%2C") : name;
}

try {
  builder.addWithChannel(name, size);
} catch (IllegalArgumentException e) {
  if (e.getMessage().contains("Cannot have a comma")) {
    builder.addWithChannel(sanitizeFileName(name), size);
  } else { throw e; }
}

When it happens

Trigger: Calling SegmentFileBuilderV10.addWithChannel(name, size) or add(name, file) where the name string contains a comma character, e.g. a column name or derived file name built from user data containing ','.

Common situations: Programmatically generating column/file names from unescaped user input or CSV-derived names; passing a filename from a config that contains commas.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot add files of the same name, already have
• 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

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

Appendix: source

Thrown at processing/src/main/java/org/apache/druid/segment/file/SegmentFileBuilderV10.java:200

          position += transferred;
        }
      }
    }
  }

  @Override
  public void add(String name, ByteBuffer bufferToAdd) throws IOException
  {
    try (SegmentFileChannel out = addWithChannel(name, bufferToAdd.remaining())) {
      out.write(bufferToAdd);
    }
  }

  @Override
  public SegmentFileChannel addWithChannel(final String name, final long size) throws IOException
  {
    if (name.contains(",")) {
      throw new IAE("Cannot have a comma in the name of a file, got[%s].", name);
    }
    if (internalFiles.containsKey(name)) {
      throw new IAE("Cannot add files of the same name, already have [%s]", name);
    }
    ensureNameMatchesActiveBundle(name);
    if (size > maxContainerSize) {
      throw DruidException.forPersona(DruidException.Persona.ADMIN)
                          .ofCategory(DruidException.Category.RUNTIME_FAILURE)
                          .build(
                              "Serialized buffer size[%,d] for column[%s] exceeds the maximum[%,d]. "
                              + "Consider adjusting the tuningConfig - for example, reduce maxRowsPerSegment, "
                              + "or partition your data further.",
                              size, name, maxContainerSize
                          );
    }

    // If an outer writer is mid-write we can't append to the current container concurrently, route through a temp
    // file that will be merged back into a container once the outer writer releases.

View on GitHub (pinned to 9b90983fd2)