What causes "params and builderQuery cannot be nil" in SigNoz/signoz?

If you see this in logs, check for a nil compositeQuery or missing builder query entry before calling the querier

params and builderQuery cannot be nil

Error message

params and builderQuery cannot be nil

What it means

Internal guard in prepareLogsQuery: both the QueryRangeParamsV3 and the individual builder query must be non-nil before a logs query can be built. A nil pointer here means upstream constructed an invalid call into runBuilderQuery.

Source

Thrown at pkg/query-service/app/querier/helper.go:31

	"github.com/SigNoz/signoz/pkg/query-service/constants"
	v3 "github.com/SigNoz/signoz/pkg/query-service/model/v3"
	"github.com/SigNoz/signoz/pkg/query-service/postprocess"
	"github.com/SigNoz/signoz/pkg/query-service/querycache"
	"github.com/SigNoz/signoz/pkg/valuer"
)

func prepareLogsQuery(
	_ context.Context,
	start,
	end int64,
	builderQuery *v3.BuilderQuery,
	params *v3.QueryRangeParamsV3,
) (string, error) {
	query := ""
	logsQueryBuilder := logsV4.PrepareLogsQuery

	if params == nil || builderQuery == nil {
		return query, fmt.Errorf("params and builderQuery cannot be nil")
	}

	// for ts query with limit replace it as it is already formed
	if params.CompositeQuery.PanelType == v3.PanelTypeGraph && builderQuery.Limit > 0 && len(builderQuery.GroupBy) > 0 {
		limitQuery, err := logsQueryBuilder(
			start,
			end,
			params.CompositeQuery.QueryType,
			params.CompositeQuery.PanelType,
			builderQuery,
			v3.QBOptions{GraphLimitQtype: constants.FirstQueryGraphLimit},
		)
		if err != nil {
			return query, err
		}
		placeholderQuery, err := logsQueryBuilder(
			start,
			end,

View on GitHub (pinned to 5069bf80b0)

Solutions

If you see this in logs, check for a nil compositeQuery or missing builder query entry before calling the querier
In tests, always construct full QueryRangeParamsV3 with at least one builder query
Report upstream if triggered via the standard API (would indicate a server bug)

Example fix

// before
runBuilderQuery(ctx, "q1", nil, nil)
// after
params := &v3.QueryRangeParamsV3{CompositeQuery: &v3.CompositeQuery{BuilderQueries: map[string]*v3.BuilderQuery{"q1": {}}}}
runBuilderQuery(ctx, "q1", params.BuilderQueries["q1"], params)

Defensive patterns

Strategy: validation

Validate before calling

if params == nil || params.CompositeQuery == nil { return errors.New("params with composite query required") }
if q, ok := params.CompositeQuery.BuilderQueries[name]; !ok || q == nil { return fmt.Errorf("builder query %q missing", name) }

Type guard

func hasBuilderQuery(p *v3.QueryRangeParamsV3, name string) bool { return p != nil && p.CompositeQuery != nil && p.CompositeQuery.BuilderQueries[name] != nil }

Prevention

Never call the querier with partially built params; construct via ParseQueryRangeParams
In tests, use builders that guarantee non-nil maps

When it happens

Trigger: Not typically reachable via normal HTTP; occurs when internal code or tests invoke runBuilderQuery with a nil params or a composite query missing that query name.

Common situations: Unit tests passing nil; programmatic use of the querier package; races where builderQueries map entries are removed during execution.

Related errors

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