apache/iceberg · error · UncheckedIOException

Failed to write Spark view query column names

Error message

Failed to write Spark view query column names

What it means

SparkViewQueryColumnNamesParser.toJson() serializes the view's query column names array to JSON. Any IOException from Jackson is rethrown as UncheckedIOException('Failed to write Spark view query column names', e), signaling serialization failed while persisting view metadata.

Source

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

package org.apache.iceberg.spark.source;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.io.IOException;
import java.io.UncheckedIOException;
import org.apache.iceberg.relocated.com.google.common.base.Preconditions;

/** Converts Spark view query column names to and from a property-safe JSON representation. */
class SparkViewQueryColumnNamesParser {
  private static final ObjectMapper MAPPER = new ObjectMapper();

  private SparkViewQueryColumnNamesParser() {}

  static String toJson(String[] columnNames) {
    try {
      return MAPPER.writeValueAsString(columnNames);
    } catch (IOException e) {
      throw new UncheckedIOException("Failed to write Spark view query column names", e);
    }
  }

  static String[] fromJson(String json) {
    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();

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Inspect getCause() for the underlying IOException
2. Check for duplicate jackson-databind versions on the classpath
3. Retry view creation; if reproducible, gather versions and file an issue
4. Avoid replacing MAPPER or its configuration in custom forks

if (columnNames == null) throw new IllegalArgumentException("Query column names are required for view metadata");

try { json = SparkViewQueryColumnNamesParser.toJson(columnNames); } catch (UncheckedIOException e) { log.error("Query column names serialization failed: {}", e.getCause(), e); throw e; }

When it happens

Trigger: MAPPER.writeValueAsString(columnNames) throwing during view creation/alter — practically caused by JsonMappingException from a bad ObjectMapper state or classpath issues, not by the String[] itself.

Common situations: Jackson version conflicts/shading on the classpath; corrupted ObjectMapper configuration; transient IO wrappers around metadata persistence.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

• Failed to write Spark view dependencies
• Failed to parse Spark view dependencies
• Unsupported Spark view dependency type:
• Failed to read StreamingOffset from json
• Renaming a view is not supported by catalog: ${catalogName}

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