apache/beam · error

bigqueryio: query parameter

Error message

bigqueryio: query parameter %q has unsupported value type %T (%v). WithQueryParameters only supports bool, string, numeric types, []byte, time.Time, civil.Date/Time/DateTime, *big.Rat, bigquery.Null* types, *bigquery.IntervalValue, *bigquery.RangeValue, and *bigquery.QueryParameterValue. For STRUCT/ARRAY parameters or other custom types, build a *bigquery.QueryParameterValue explicitly instead

What it means

encodeQueryParameters serializes bigquery.QueryParameter values with gob so they can travel with the query to workers. Before encoding, each parameter is test-encoded; any value type gob cannot encode (channels, funcs, unregistered concrete types, etc.) produces this long error naming the parameter, its Go type, and the gob error. STRUCT/ARRAY parameters must be built as *bigquery.QueryParameterValue explicitly.

Solutions

1. For STRUCT/ARRAY parameters, construct a *bigquery.QueryParameterValue with the right Type and ArrayValue/StructValue fields instead of a raw Go value.
2. Restrict WithQueryParameters values to the supported set: bool, strings, numerics, []byte, time.Time, civil.Date/Time/DateTime, *big.Rat, bigquery.Null*, *bigquery.IntervalValue, *bigquery.RangeValue.
3. If a custom named scalar type is intended, convert it to its underlying primitive (string(p), int64(i)) before passing it.
4. Run the parameter through gob encoding locally first to confirm encodability before submitting the query.

Example fix

// before
params := bigqueryio.WithQueryParameters([]bigquery.QueryParameter{
  {Name: "filter", Value: myStruct{}}, // gob cannot encode
})

// after
qv, _ := bigquery.QueryParameterValueFromSchema(mySchema) // or build manually
params := bigqueryio.WithQueryParameters([]bigquery.QueryParameter{
  {Name: "filter", ParameterType: &bigquery.QueryParameterType{Type: "STRUCT", StructTypes: st}, ParameterValue: &bigquery.QueryParameterValue{StructValues: vals}},
})

func validateParams(params []bigquery.QueryParameter) error {
	for _, p := range params {
		if err := gob.NewEncoder(io.Discard).Encode([]bigquery.QueryParameter{p}); err != nil {
			return fmt.Errorf("parameter %q of type %T is not supported: %w", p.Name, p.Value, err)
		}
	}
	return nil
}

func isSupportedParamValue(v any) bool {
	switch v.(type) {
	case bool, string, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float32, float64, []byte, time.Time, civil.Date, civil.Time, civil.DateTime, *big.Rat, *bigquery.IntervalValue, *bigquery.RangeValue, *bigquery.QueryParameterValue:
		return true
	default:
		return false
	}
}

When it happens

Trigger: Calling bigqueryio.Query with WithQueryParameters containing a parameter whose Value is a type outside the supported set: e.g. a custom struct, map, slice of structs, channel, or func.

Common situations: Passing a Go struct as a STRUCT parameter directly; passing []MyType for an ARRAY parameter; gob-unregistered custom named types (e.g. a custom string type) that gob refuses to encode; upgrading code that previously used only scalars to complex parameters.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

• bigquery write error
• bigquery write error
• bigqueryio.Query: failed to encode query parameters
• bigqueryio.queryFn: failed to decode query parameters
• bigqueryio.Read: type

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

Appendix: source

Thrown at sdks/go/pkg/beam/io/bigqueryio/coder.go:63

	gob.Register(bigquery.NullGeography{})
	gob.Register(bigquery.NullJSON{})
	gob.Register(civil.Date{})
	gob.Register(civil.Time{})
	gob.Register(civil.DateTime{})
	gob.Register(time.Time{})
	gob.Register(&big.Rat{})
	gob.Register(&bigquery.IntervalValue{})
	gob.Register(&bigquery.RangeValue{})
}

func encodeQueryParameters(params []bigquery.QueryParameter) ([]byte, error) {
	if params == nil {
		return []byte{}, nil
	}
	// validate each element to tell which parameter is unsupported.
	for _, p := range params {
		if err := gob.NewEncoder(io.Discard).Encode([]bigquery.QueryParameter{p}); err != nil {
			return nil, errors.Errorf(
				"bigqueryio: query parameter %q has unsupported value type %T (%v). "+
					"WithQueryParameters only supports bool, string, numeric types, []byte, "+
					"time.Time, civil.Date/Time/DateTime, *big.Rat, bigquery.Null* types, "+
					"*bigquery.IntervalValue, *bigquery.RangeValue, and *bigquery.QueryParameterValue. "+
					"For STRUCT/ARRAY parameters or other custom types, build a "+
					"*bigquery.QueryParameterValue explicitly instead", p.Name, p.Value, err)
		}
	}
	var buf bytes.Buffer
	if err := gob.NewEncoder(&buf).Encode(params); err != nil {
		return nil, err
	}
	return buf.Bytes(), nil
}

func decodeQueryParameters(data []byte) ([]bigquery.QueryParameter, error) {
	if len(data) == 0 {
		return []bigquery.QueryParameter{}, nil

View on GitHub (pinned to 12126d8942)