bigqueryio.Query: failed to encode query parameters

Error message

bigqueryio.Query: failed to encode query parameters

What it means

In query (sdks/go/pkg/beam/io/bigqueryio/bigquery.go), the user-supplied query parameters are serialized on the driver side via encodeQueryParameters before being embedded in the ParDo; failure is wrapped as "bigqueryio.Query: failed to encode query parameters" and panics. It means a query parameter value has a type or value BigQuery IO cannot serialize.

Solutions

Restrict query parameters to supported scalar/slice types (string, numeric, bool, time.Time, []byte).
Inspect the wrapped err to identify the offending parameter and convert it to a supported type.
For complex values, serialize them yourself (e.g. JSON into a string parameter) and parse inside the query.
Use beam.TryQuery-style construction if available, or recover the panic in a wrapper to fail gracefully at pipeline build time.

Example fix

// before
params := []bigqueryio.QueryParameter{{Name: "f", Value: myStruct{}}}
beamio.Query(s, proj, sql, t, params...)
// after
params := []bigqueryio.QueryParameter{{Name: "f", Value: myStruct.ID}} // supported scalar
beamio.Query(s, proj, sql, t, params...)

Defensive patterns

Strategy: validation

Validate before calling

func validateQueryParams(ps []bigqueryio.QueryParameter) error {
    for _, p := range ps {
        switch p.Value.(type) {
        case nil, string, int, int64, float64, bool, time.Time, []byte:
        default:
            return fmt.Errorf("unsupported query parameter type %T for %q", p.Value, p.Name)
        }
    }
    return nil
}

Try / catch

func safeQuery(...) (beam.PCollection, error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("query setup failed: %v", r)
        }
    }()
    return beamio.Query(s, proj, sql, t, params...), nil
}

Prevention

Only pass scalar and scalar-slice query parameter values
Serialize complex values to strings yourself before querying
Validate parameter types at pipeline construction time

When it happens

Trigger: Calling beamio.Query with queryOptions.parameters containing a value of an unsupported Go type (e.g. an arbitrary struct, map, or nil value) in the query parameter list.

Common situations: Passing Go-native types not in the supported parameter set (string, int/float, bool, time.Time, []byte, slices of scalars) as QueryParameter values.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/ef96e2e69ea89487. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/io/bigqueryio/bigquery.go:161

func Query(s beam.Scope, project, q string, t reflect.Type, options ...func(*QueryOptions) error) beam.PCollection {
	s = s.Scope("bigquery.Query")
	return query(s, project, q, t, options...)
}

func query(s beam.Scope, project, query string, t reflect.Type, options ...func(*QueryOptions) error) beam.PCollection {
	mustInferSchema(t)

	queryOptions := QueryOptions{}
	for _, opt := range options {
		if err := opt(&queryOptions); err != nil {
			panic(err)
		}
	}

	imp := beam.Impulse(s)
	queryParameters, err := encodeQueryParameters(queryOptions.parameters)
	if err != nil {
		panic(errors.Wrapf(err, "bigqueryio.Query: failed to encode query parameters"))
	}
	return beam.ParDo(
		s,
		&queryFn{Project: project, Query: query, Type: beam.EncodedType{T: t}, QueryParameters: queryParameters, Options: queryOptions},
		imp,
		beam.TypeDefinition{Var: beam.XType, T: t},
	)
}

type queryFn struct {
	// Project is the project.
	Project string `json:"project"`
	// Query is the query statement.
	Query string `json:"query"`
	// Type is the encoded schema type.
	Type beam.EncodedType `json:"type"`
	// QueryParameters are serialized query parameters for parameterized queries.
	QueryParameters []byte `json:"query_parameters"`

View on GitHub (pinned to 12126d8942)