apache/seatunnel · error · SeaTunnelException

Invalid metalake table id:

Error message

Invalid metalake table id: 

What it means

SeaTunnelException thrown by buildMetalakeUrlTableUrl when the metaDataTableId does not split into exactly 3 dot-separated parts (catalog.schema.table). The provider cannot construct the Gravitino table URL without all three segments.

Source

Thrown at seatunnel-api/src/main/java/org/apache/seatunnel/api/metadata/gravitino/GravitinoMetadataProvider.java:202

        } catch (IOException e) {
            throw new SeaTunnelException("fail get tableSchema:" + metaDataTableId, e);
        }
    }

    /**
     * Builds the metalake URL for Gravitino API calls.
     *
     * @return complete metalake URL
     */
    private String buildMetalakeUrl() {
        String baseUri = uri.endsWith("/") ? uri : uri + "/";
        return baseUri + METALAKE_API_PATH + metalake + CATALOGS_PATH;
    }

    private String buildMetalakeUrlTableUrl(String metaDataTableId) {
        final String[] split = metaDataTableId.split("\\.");
        if (split.length != 3) {
            throw new SeaTunnelException("Invalid metalake table id: " + metaDataTableId);
        }
        String catalog = split[0];
        String schema = split[1];
        String table = split[2];
        String baseUri = uri.endsWith("/") ? uri : uri + "/";
        return baseUri
                + METALAKE_API_PATH
                + metalake
                + CATALOGS_PATH
                + "/"
                + catalog
                + SCHEMAS_PATH
                + "/"
                + schema
                + TABLES_PATH
                + "/"
                + table;
    }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Pass the id as exactly "catalog.schema.table" with three dot-separated parts.
2. Trim or unquote the identifier if it contains escaped dots or whitespace.
3. If the input may be a URL, extract catalog/schema/table first instead of passing the URL string.

Example fix

// before
provider.tableSchema("mydb.mytable");
// after
provider.tableSchema("mycatalog.mydb.mytable");

static boolean isValidMetalakeTableId(String id) {
    if (id == null) return false;
    String[] parts = id.split("\\.");
    return parts.length == 3 && java.util.Arrays.stream(parts).allMatch(p -> !p.isEmpty());
}
// call before: if (!isValidMetalakeTableId(tableId)) throw new IllegalArgumentException(tableId);

try {
    return provider.tableSchema(tableId);
} catch (SeaTunnelException e) {
    if (e.getMessage().startsWith("Invalid metalake table id")) {
        throw new IllegalArgumentException("Expected 'catalog.schema.table', got: " + tableId);
    }
    throw e;
}

When it happens

Trigger: Calling tableSchema() with an id like "mydb.mytable" (missing catalog), "catalog..table" (empty schema), or an id using different separators than '.'.

Common situations: Users passing a two-part table identifier copied from a JDBC/Spark context; extra dots from quoted identifiers; passing a full Gravitino HTTP URL instead of the dotted id.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Table URL cannot be null or empty
• Invalid table URL format: '%s'. Expected format: http://host
• Condition operator must not be null
• Failed to fetch metadata from Gravitino for metadata: %s
• fail get tableSchema:

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