jackc/pgx · error

StructArgs requires a non-nil pointer to struct

Error message

StructArgs requires a non-nil pointer to struct

What it means

StructArgs received a typed nil pointer to a struct. reflection cannot dereference a nil pointer to read fields, so the guard rejects it explicitly.

Solutions

1. Initialize the struct before taking its address
2. Guard call sites that may pass nil pointers

When it happens

Trigger: Thrown at named_args.go:84 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of jackc/pgx@ec1a0befd2 (2026-08-04). Data as JSON: /api/errors/b181fe997f4864e5. Report an issue: GitHub.

Appendix: source

Thrown at named_args.go:84

func StrictStructArgs(sa any) QueryRewriter {
	args, err := structArgs(sa)
	if err != nil {
		return errorQueryRewriter{err: err}
	}
	return StrictNamedArgs(args)
}

func structArgs(sa any) (map[string]any, error) {
	if sa == nil {
		return nil, fmt.Errorf("StructArgs requires a struct or pointer to struct, got nil")
	}

	v := reflect.ValueOf(sa)
	t := v.Type()

	if t.Kind() == reflect.Pointer {
		if v.IsNil() {
			return nil, fmt.Errorf("StructArgs requires a non-nil pointer to struct")
		}
		v = v.Elem()
		t = v.Type()
	}

	if t.Kind() != reflect.Struct {
		return nil, fmt.Errorf("StructArgs requires a struct or pointer to struct, got %s", t)
	}

	out := make(map[string]any, t.NumField())
	for i := 0; i < t.NumField(); i++ {
		sf := t.Field(i)

		// Ignore unexported fields.
		if sf.PkgPath != "" {
			continue
		}

View on GitHub (pinned to ec1a0befd2)