What causes "Failed to parse shallow keys from Firebase response" in apache/seatunnel?

Log/inspect the underlying cause 'e' to see the raw response; verify the URL returns real JSON (curl the endpoint).

apache/seatunnel · error · SeaTunnelException

Failed to parse shallow keys from Firebase response

Error message

Failed to parse shallow keys from Firebase response

What it means

parseShallowKeys parses the JSON response of a Firebase shallow REST query expecting an object mapping keys to booleans (Map<String, Boolean>). If the body is malformed JSON or not a JSON object, Jackson fails and the error is wrapped in a SeaTunnelException. It signals the Firebase endpoint returned something the client could not interpret as a shallow key listing.

Source

Thrown at seatunnel-connectors-v2/connector-firebase/src/main/java/org/apache/seatunnel/connectors/seatunnel/firebase/client/FirebaseHttpClient.java:117

        return parseShallowKeys(jsonResponse);
    }

    /** Parses the JSON payload returned by a shallow scan query. */
    List<String> parseShallowKeys(String jsonResponse) {
        if (jsonResponse == null || jsonResponse.trim().equals("null")) {
            return Collections.emptyList();
        }
        String trimmed = jsonResponse.trim();
        if (!trimmed.startsWith("{")) {
            return Collections.emptyList();
        }

        try {
            Map<String, Boolean> keysMap =
                    OBJECT_MAPPER.readValue(trimmed, new TypeReference<Map<String, Boolean>>() {});
            return new ArrayList<>(keysMap.keySet());
        } catch (Exception e) {
            throw new SeaTunnelException("Failed to parse shallow keys from Firebase response", e);
        }
    }

    /**
     * Fetches the raw JSON payload for a given sub-path or individual node key. Endpoint: GET
     * /<path>/<nodeKey>.json
     */
    public String fetchNodeData(String nodeKey) {
        String targetPath =
                nodeKey == null || nodeKey.isEmpty() ? this.path : this.path + "/" + nodeKey;

        String endpointUrl = buildUrl(targetPath, null, true);
        return executeGet(endpointUrl);
    }

    /** Constructs a full REST URL with .json extension and query string parameters. */
    String buildUrl(String subPath, String extraQueryParam, boolean includeExtraParams) {
        StringBuilder urlBuilder = new StringBuilder(baseUrl);

View on GitHub (pinned to cf67b549a7)

Solutions

Log/inspect the underlying cause 'e' to see the raw response; verify the URL returns real JSON (curl the endpoint).
Check authentication: ensure service account credentials or auth token are valid so Firebase returns JSON, not an HTML error page.
Confirm the configured path points to an object node, not a scalar leaf.
Validate the base URL has no typos and no proxy is rewriting the response.

Example fix

null

Defensive patterns

Strategy: try-catch

Validate before calling

String body = executeGet(url);
String trimmed = body == null ? "" : body.trim();
if (!trimmed.startsWith("{")) throw new IllegalStateException("non-JSON shallow keys response: " + trimmed);

Try / catch

try { keys = client.fetchShallowKeys(); } catch (SeaTunnelException e) { log.error("shallow keys parse failed", e.getCause()); throw e; }

Prevention

Curl the shallow endpoint first to confirm JSON output
Ensure auth is valid so Firebase does not return HTML error pages
Point the path at an object node, not a scalar
Check for proxies rewriting response bodies

When it happens

Trigger: GET /<path>.json?shallow=true returning HTML (auth error page), a plain string, an array, or truncated/invalid JSON; proxy or firewall injecting an error page; expired auth token returning a non-object error body.

Common situations: Wrong base URL pointing at a non-Firebase host; missing/invalid auth producing HTML error responses; path pointing at a leaf value (string/number) instead of a node; network middleware (captive portal) corrupting responses.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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