prestodb/presto · error · IllegalArgumentException

Unsupported EXPLAIN type:

Error message

Unsupported EXPLAIN type: 

What it means

AstBuilder.visitExplainType throws this IllegalArgumentException when an EXPLAIN TYPE clause carries a token other than LOGICAL, DISTRIBUTED, VALIDATE or IO. Like the format variant, the grammar only produces known tokens, so this indicates a fork/grammar mismatch or an unhandled enum case.

Source

Thrown at presto-parser/src/main/java/com/facebook/presto/sql/parser/AstBuilder.java:1352

        throw new IllegalArgumentException("Unsupported EXPLAIN format: " + context.value.getText());
    }

    @Override
    public Node visitExplainType(SqlBaseParser.ExplainTypeContext context)
    {
        switch (context.value.getType()) {
            case SqlBaseLexer.LOGICAL:
                return new ExplainType(getLocation(context), ExplainType.Type.LOGICAL);
            case SqlBaseLexer.DISTRIBUTED:
                return new ExplainType(getLocation(context), ExplainType.Type.DISTRIBUTED);
            case SqlBaseLexer.VALIDATE:
                return new ExplainType(getLocation(context), ExplainType.Type.VALIDATE);
            case SqlBaseLexer.IO:
                return new ExplainType(getLocation(context), ExplainType.Type.IO);
        }

        throw new IllegalArgumentException("Unsupported EXPLAIN type: " + context.value.getText());
    }

    @Override
    public Node visitShowTables(SqlBaseParser.ShowTablesContext context)
    {
        return new ShowTables(
                getLocation(context),
                Optional.ofNullable(context.qualifiedName())
                        .map(this::getQualifiedName),
                getTextIfPresent(context.pattern)
                        .map(AstBuilder::unquote),
                getTextIfPresent(context.escape)
                        .map(AstBuilder::unquote));
    }

    @Override
    public Node visitShowSchemas(SqlBaseParser.ShowSchemasContext context)
    {

View on GitHub (pinned to 55bb57d202)

Solutions

1. Use one of the supported types: LOGICAL, DISTRIBUTED, VALIDATE, or IO.
2. Omit the TYPE clause to use the default.
3. In a fork, add a case for the new token plus a matching ExplainType.Type enum constant.
4. Regenerate the parser from the same SqlBase.g4 that AstBuilder was written against.

Example fix

// before
EXPLAIN (TYPE PHYSICAL) SELECT * FROM t;
// after
EXPLAIN (TYPE DISTRIBUTED) SELECT * FROM t;

Set<String> allowed = Set.of("LOGICAL", "DISTRIBUTED", "VALIDATE", "IO");
if (type != null && !allowed.contains(type.toUpperCase(Locale.ROOT))) {
    throw new IllegalArgumentException("EXPLAIN TYPE must be LOGICAL, DISTRIBUTED, VALIDATE or IO");
}

boolean isSupportedExplainType(String s) {
    return s != null && Set.of("LOGICAL", "DISTRIBUTED", "VALIDATE", "IO")
        .contains(s.toUpperCase(Locale.ROOT));
}

try {
    parser.createStatement(sql);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unsupported EXPLAIN type")) {
        sql = sql.replaceFirst("(?i)TYPE\\s+\\S+", "TYPE LOGICAL");
        parser.createStatement(sql);
    } else throw e;
}

When it happens

Trigger: Running 'EXPLAIN (TYPE <x>) ...' where the type token is not one of the four handled values, or a parser build where the grammar's ExplainTypeContext accepts tokens AstBuilder does not switch on.

Common situations: Scripts migrated from other SQL engines using unsupported EXPLAIN types, forked grammars with a new type added only to the .g4 file.

Related errors

• Unsupported EXPLAIN format:
• Unsupported join criteria
• WARNING_AS_ERROR
• Invalid day-time interval:
• Invalid year-month interval:

AI-assisted analysis of prestodb/presto@55bb57d202 (2026-09-04). Data as JSON: /api/errors/f06eb801230706e1. Report an issue: GitHub.