pinpoint-apm/pinpoint · error · InvalidParameterException

TimeWindow is required.

Error message

TimeWindow is required.

What it means

OtlpMetricDataQueryParameter's builder enforces in build() that a TimeWindow was supplied before constructing the object; otherwise it throws InvalidParameterException. The data query parameter needs the time window to compute the query range and aggregation interval against the pinot/metric storage.

Solutions

1. Ensure the parent OtlpMetricChartQueryParameter is built with a TimeWindow before data query parameters are derived from it.
2. Call .timeWindow(...) on the data query builder explicitly in every construction path.
3. Validate request time range (from/to/interval) at the API boundary so a missing window never reaches the builder.
4. Check the fix for error 461 first — this error is usually a symptom of it.

Example fix

// before
builder.setMetricGroupName(group).setMetricName(name).build(); // timeWindow missing
// after
builder.setMetricGroupName(group).setMetricName(name)
       .setTimeWindow(chartParameter.getTimeWindow())
       .build();

Objects.requireNonNull(chartParam.getTimeWindow(), "parent chart parameter must carry a TimeWindow before deriving data query parameters");

boolean canBuildDataQuery(OtlpMetricDataQueryParameter.DataQueryBuilder b) {
    return b.getTimeWindow() != null;
}

try {
    List<OtlpMetricDataQueryParameter> list = setupQueryParameter(builder, fields, tagGroup);
} catch (InvalidParameterException e) {
    log.error("data query parameter missing TimeWindow", e);
    throw new InvalidRequestException("time range required", e);
}

When it happens

Trigger: Calling OtlpMetricDataQueryParameter.DataQueryBuilder.build() without a prior timeWindow(...) call, e.g. when setupQueryParameter constructs per-field/per-tag query parameters from a chart parameter that itself lacked a TimeWindow.

Common situations: Downstream of error 461: a chart parameter built without TimeWindow propagates a null window into data query parameters; code that clones or copies query parameters and drops the window field; tests building minimal parameters.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• TimeWindow is required.
• annotationKey name must not be empty
• Either tagGroupList or fieldNameList must have a size of…
• eventIdentifier cannot be less than 0
• invalid operator - not found left operand. operator=

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/acfb60d86572c891. Report an issue: GitHub.

Appendix: source

Thrown at otlpmetric/otlpmetric-web/src/main/java/com/navercorp/pinpoint/otlp/web/vo/OtlpMetricDataQueryParameter.java:186

            } else {
                return doubleTableNameManager.getTableName(this.applicationName);
            }
        }

        public Builder setDoubleTableNameManager(TableNameManager doubleTableNameManager) {
            this.doubleTableNameManager = doubleTableNameManager;
            return self();
        }

        public Builder setLongTableNameManager(TableNameManager longTableNameManager) {
            this.longTableNameManager = longTableNameManager;
            return self();
        }

        @Override
        public OtlpMetricDataQueryParameter build() {
            if (timeWindow == null) {
                throw new InvalidParameterException("TimeWindow is required.");
            }

            return new OtlpMetricDataQueryParameter(this);
        }
    }

    @Override
    public String toString() {
        return "OtlpMetricDataQueryParameter{" +
                "tableName='" + tableName + '\'' +
                ", serviceName='" + serviceName + '\'' +
                ", applicationName='" + applicationName + '\'' +
                ", agentId='" + agentId + '\'' +
                ", metricGroupName='" + metricGroupName + '\'' +
                ", metricName='" + metricName + '\'' +
                ", fieldName='" + fieldName + '\'' +
                ", tags=" + tags +
                ", rawTags='" + rawTags + '\'' +

View on GitHub (pinned to 744c3d3075)