apache/druid · error · IAE

When a local external table is used with a table function

Error message

When a local external table is used with a table function, %s must be set

What it means

When a local external table's stored input source has no files list, the table must define a baseDir property, because any table-function arguments (files/filter) are resolved relative to that directory. If the stored table lacks baseDir, convertCompletedTable throws this IAE naming the missing field.

Solutions

1. Add a baseDir property to the table definition
2. Add a files property to the table definition instead
3. Recreate the table definition through the catalog API so validation runs

Example fix

// before
{"type":"local"}
// after
{"type":"local","baseDir":"/data/incoming"}

// Java
Map<String,Object> src = table.inputSourceMap;
boolean ok = !CollectionUtils.isNullOrEmpty((List<?>) src.getOrDefault("files", List.of()))
          || !Strings.isNullOrEmpty((String) src.get("baseDir"));
if (!ok) throw new IllegalArgumentException("table needs files or baseDir property");

try { fn.call(args); } catch (IAE e) { if (e.getMessage().contains("must be set")) { /* set baseDir on the table definition */ } else throw e; }

When it happens

Trigger: Invoking a table function on a local external table whose inputSourceMap has neither files nor baseDir set (e.g. created without validation or via a partial definition).

Common situations: Hand-edited or imported table specs missing baseDir; tables created before validation rules tightened; programmatically built definitions that only set type and format.

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

• Use a table function to set either
• A local input source requires one parameter of
• For a local input source, set either
• If a local input source sets parameter
• The local input source has a file list: do not provide…

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

Appendix: source

Thrown at server/src/main/java/org/apache/druid/catalog/model/table/LocalInputSourceDefn.java:216

  }

  @Override
  protected ExternalTableSpec convertCompletedTable(
      final ResolvedExternalTable table,
      final Map<String, Object> args,
      final List<ColumnSpec> columns
  )
  {
    final Map<String, Object> sourceMap = new HashMap<>(table.inputSourceMap);
    final boolean hasFiles = !CollectionUtils.isNullOrEmpty(CatalogUtils.safeGet(sourceMap, FILES_FIELD, List.class));
    if (hasFiles) {
      if (!args.isEmpty()) {
        throw new IAE("The local input source has a file list: do not provide other arguments");
      }
    } else {
      final String baseDir = CatalogUtils.getString(sourceMap, BASE_DIR_FIELD);
      if (Strings.isNullOrEmpty(baseDir)) {
        throw new IAE(
            "When a local external table is used with a table function, %s must be set",
            BASE_DIR_FIELD
        );
      }
      final boolean hasFilter = !Strings.isNullOrEmpty(CatalogUtils.getString(sourceMap, FILTER_FIELD));
      final List<String> filesParam = CatalogUtils.getStringArray(args, FILES_PARAMETER);
      final boolean hasFilesParam = !CollectionUtils.isNullOrEmpty(filesParam);
      final String filterParam = CatalogUtils.getString(args, FILTER_PARAMETER);
      final boolean hasFilterParam = !Strings.isNullOrEmpty(filterParam);
      if (!hasFilter && !hasFilesParam && !hasFilterParam) {
        throw new IAE(
            "For a local input source, set either %s or %s",
            FILES_PARAMETER,
            FILTER_PARAMETER
        );
      }
      if (hasFilesParam) {
        // Special workaround: if the user provides a base dir, and files, convert

View on GitHub (pinned to 9b90983fd2)