SigNoz/signoz · error

composite query is required

Error message

composite query is required

What it means

CompositeQuery.Validate() returns this when the CompositeQuery itself is nil. The server unmarshals the request body into *CompositeQuery; a missing/invalid compositeQuery section leaves it nil and validation fails immediately.

Source

Thrown at pkg/query-service/model/v3/v3.go:610

	}
	return count
}

func (c *CompositeQuery) Sanitize() {
	if c == nil {
		return
	}
	// remove groupBy for queries with list panel type
	for _, query := range c.BuilderQueries {
		if len(query.GroupBy) > 0 && c.PanelType == PanelTypeList {
			query.GroupBy = []AttributeKey{}
		}
	}
}

func (c *CompositeQuery) Validate() error {
	if c == nil {
		return fmt.Errorf("composite query is required")
	}

	if c.BuilderQueries == nil && c.ClickHouseQueries == nil && c.PromQueries == nil && len(c.Queries) == 0 {
		return fmt.Errorf("composite query must contain at least one query type")
	}

	if c.QueryType == QueryTypeBuilder {
		for name, query := range c.BuilderQueries {
			if err := query.Validate(c.PanelType); err != nil {
				return fmt.Errorf("builder query %s is invalid: %w", name, err)
			}
		}
	}

	if c.QueryType == QueryTypeClickHouseSQL {
		for name, query := range c.ClickHouseQueries {
			if err := query.Validate(); err != nil {
				return fmt.Errorf("clickhouse query %s is invalid: %w", name, err)

View on GitHub (pinned to 5069bf80b0)

Solutions

1. Ensure the request body contains a compositeQuery object with queryType, panelType, and at least one query collection
2. Verify JSON nesting matches the API schema: {"compositeQuery":{"queryType":"builder",...}}
3. Check the HTTP response/error for unmarshal issues if you believe you are sending it

Example fix

// before
{"queryType":"promql","promQueries":{"A":{"query":"up"}}}

// after
{"compositeQuery":{"queryType":"promql","panelType":"graph","promQueries":{"A":{"query":"up"}}}}

if cq == nil { return errors.New("compositeQuery is missing — check request body structure") }

func hasCompositeQuery(body []byte) bool { var b struct{ CompositeQuery *json.RawMessage `json:"compositeQuery"` }; _ = json.Unmarshal(body, &b); return b.CompositeQuery != nil }

When it happens

Trigger: POSTing /api/v3/query_range with a body that has no compositeQuery field at all, a malformed JSON body where unmarshalling silently leaves the struct nil, or passing a nil *v3.CompositeQuery programmatically to code that calls Validate().

Common situations: Client built against an older API shape without compositeQuery, JSON nesting errors (putting queryType at top level instead of inside compositeQuery), or code paths calling Validate on a zero-valued request.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• composite query must contain at least one query type
• filterAttributeKey is required
• startTimeMillis is required
• endTimeMillis is required
• query is empty

AI-assisted analysis of SigNoz/signoz@5069bf80b0 (2026-08-28). Data as JSON: /api/errors/9922ca5c1e6c866d. Report an issue: GitHub.