apache/iceberg · error · UncheckedIOException

Failed to parse Spark view query column names

Error message

Failed to parse Spark view query column names

What it means

This UncheckedIOException is thrown by SparkViewQueryQueryColumnNamesParser.fromJson when Jackson fails to read the JSON representation of a Spark view query's column names. It wraps the underlying IOException so callers get a runtime exception with a clear message about what JSON structure failed to parse.

Solutions

1. Validate the JSON string parses to the expected array of column names before calling fromJson
2. Catch UncheckedIOException at the call site and log/inspect the offending JSON payload
3. Check that the view metadata was written by a compatible Iceberg/Spark version and rewrite the view if it is corrupted

Example fix

// before
String[] cols = SparkViewQueryQueryColumnNamesParser.fromJson(json);
// after
String[] cols;
try {
  cols = SparkViewQueryQueryColumnNamesParser.fromJson(json);
} catch (UncheckedIOException e) {
  LOG.error("Bad view query column names JSON: {}", json, e);
  throw e;
}

// Java
if (json == null || !json.trim().startsWith("[")) {
  throw new IllegalArgumentException("Expected JSON array of column names, got: " + json);
}
JsonUtil.mapper().readTree(json); // pre-validate parseability

boolean isColumnNameNamesJson(String json) {
  try { return json != null && JsonUtil.mapper().readTree(json).isArray(); }
  catch (IOException e) { return false; }
}

try {
  String[] cols = SparkViewQueryQueryColumnNamesParser.fromJson(json);
} catch (UncheckedIOException e) {
  // e.getCause() is the Jackson IOException; inspect/log json
  throw new IllegalArgumentException("Corrupt view column names JSON", e);
}

When it happens

Trigger: Calling SparkViewQueryQueryColumnNamesParser.fromJson(String) with malformed JSON, a JSON node that is not the expected array of text values, or JSON that cannot be deserialized by JsonUtil.mapper().

Common situations: Corrupted or hand-edited view metadata JSON, version drift where the stored view representation changed shape (e.g. older/newer Spark writing different JSON), or passing a non-JSON string recovered from a catalog property.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

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

Related errors

• Failed to parse Spark view dependencies
• Failed to parse StreamingOffset from JSON string
• Failed to parse StreamingOffset from JSON string
• Failed to read json file
• Failed to read StreamingOffset from json

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/3fd0caa83485ca51. Report an issue: GitHub.

Appendix: source

Thrown at spark/v4.2/spark/src/main/java/org/apache/iceberg/spark/source/SparkViewQueryColumnNamesParser.java:60

    try {
      JsonNode node = MAPPER.readTree(json);
      Preconditions.checkArgument(
          node != null && node.isArray(),
          "Cannot parse Spark view query column names from non-array: %s",
          node);
      String[] columnNames = new String[node.size()];
      for (int index = 0; index < node.size(); index += 1) {
        JsonNode columnName = node.get(index);
        Preconditions.checkArgument(
            columnName.isTextual(),
            "Cannot parse Spark view query column name from non-string: %s",
            columnName);
        columnNames[index] = columnName.asText();
      }

      return columnNames;
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to parse Spark view query column names", e);
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)