---
title: "positions_increment_gap 必须为正数，得到 v – 如何解决此 Elasticsearch 异常"
date: 2026-03-07
lastmod: 2026-03-07
description: "当 Elasticsearch 中的 positions_increment_gap 参数被设置为负值或零时，会发生此错误。该参数用于在处理数组字段时设置索引词项之间的间隔。"
tags: ["映射错误", "参数验证", "数组字段"]
summary: "版本： 7.1-7.1
 简而言之，当 Elasticsearch 中的"positions_increment_gap"参数被设置为负值或零时，会发生此错误。该参数用于在处理数组字段时设置索引词项之间的间隔。要解决此问题，请确保"positions_increment_gap"被设置为正整数。这可以通过更新索引的映射或在创建新索引时来完成。请始终记住在应用设置之前进行验证，以避免此类错误。
日志上下文 #  日志"[positions_increment_gap] must be positive; got [" + v + “]“的类名是 AnnotatedTextFieldMapper.java。我们从 Elasticsearch 源代码中提取了以下内容，以便为那些寻求深入上下文的人提供参考：
final Parameter<Integer> positionIncrementGap = Parameter.intParam("position_increment_gap", false, m -> builder(m).positionIncrementGap.getValue(), POSITION_INCREMENT_GAP_USE_ANALYZER) .setValidator(v -> { if (v != POSITION_INCREMENT_GAP_USE_ANALYZER && v < 0) { throw new MapperParsingException("[positions_increment_gap] must be positive; got [" + v + "]"); } }); private final Parameter<Float> boost = Parameter.boostParam(); private final Parameter<Map<String, String>> meta = Parameter."
---



> **版本：** 7.1-7.1

简而言之，当 Elasticsearch 中的"positions_increment_gap"参数被设置为负值或零时，会发生此错误。该参数用于在处理数组字段时设置索引词项之间的间隔。要解决此问题，请确保"positions_increment_gap"被设置为正整数。这可以通过更新索引的映射或在创建新索引时来完成。请始终记住在应用设置之前进行验证，以避免此类错误。

日志上下文
-----------

日志"[positions\_increment\_gap] must be positive; got [" + v + "]"的类名是 AnnotatedTextFieldMapper.java。我们从 Elasticsearch 源代码中提取了以下内容，以便为那些寻求深入上下文的人提供参考：

```java
final Parameter<Integer> positionIncrementGap = Parameter.intParam("position_increment_gap", false,
    m -> builder(m).positionIncrementGap.getValue(), POSITION_INCREMENT_GAP_USE_ANALYZER)
    .setValidator(v -> {
        if (v != POSITION_INCREMENT_GAP_USE_ANALYZER && v < 0) {
            throw new MapperParsingException("[positions_increment_gap] must be positive; got [" + v + "]");
        }
    });
    private final Parameter<Float> boost = Parameter.boostParam();
    private final Parameter<Map<String, String>> meta = Parameter.metaParam();
```