apache/iceberg · warning

Ignoring invalid metrics mode

Error message

Ignoring invalid metrics mode ({}): {}

What it means

MetricsConfig.parseMode parses a user-supplied metrics mode string (columns.metrics.<col> or write.metrics.default) via MetricsModes.fromString. If the string is not a valid mode (none/count/truncate(L)/full or malformed), the invalid value is logged with this warning and the fallback/default mode is used instead of failing.

Solutions

1. Use one of the valid modes: none, count, truncate(N), full.
2. Fix truncate syntax, e.g. truncate(16), including a positive length.
3. Remove the invalid property so the default mode applies.
4. Quote column names with dots or special characters per property-key rules.

Example fix

// before
props.put("write.metadata.metrics.column.id", "truncat(8)");
// after
props.put("write.metadata.metrics.column.id", "truncate(8)");

java.util.Set<String> valid = Set.of("none", "count", "full");
if (!valid.contains(mode) && !mode.matches("truncate\\(\\d+\\)")) throw new IllegalArgumentException("invalid metrics mode: " + mode);

When it happens

Trigger: Setting 'write.metadata.metrics.default' or 'write.metadata.metrics.column.<name>' to a misspelled or malformed value such as 'truncat(16)', 'string', or 'NONE ' with unexpected case/whitespace that fails parsing, then writing data.

Common situations: Typos in truncate syntax (missing length or parenthesis), unknown mode names, column names with special characters requiring quoting, config copied from other engines.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Invalid unit
• Invalid value for (negative): , falling back to
• Unsupported compression codec:
• Unsupported compression strategy:
• Cannot assume role to sign REST requests because is not…

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

Appendix: source

Thrown at core/src/main/java/org/apache/iceberg/MetricsConfig.java:358

            METRICS_MAX_INFERRED_COLUMN_DEFAULTS_DEFAULT);
    if (maxInferredDefaultColumns < 0) {
      LOG.warn(
          "Invalid value for {} (negative): {}, falling back to {}",
          METRICS_MAX_INFERRED_COLUMN_DEFAULTS,
          maxInferredDefaultColumns,
          METRICS_MAX_INFERRED_COLUMN_DEFAULTS_DEFAULT);
      return METRICS_MAX_INFERRED_COLUMN_DEFAULTS_DEFAULT;
    } else {
      return maxInferredDefaultColumns;
    }
  }

  private static MetricsMode parseMode(String modeString, MetricsMode fallback, String context) {
    try {
      return MetricsModes.fromString(modeString);
    } catch (IllegalArgumentException err) {
      // User override was invalid, log the error and use the default
      LOG.warn("Ignoring invalid metrics mode ({}): {}", context, modeString, err);
      return fallback;
    }
  }
}

View on GitHub (pinned to 86d9c8fc54)