jackc/pgx · error

duplicate StructArgs key

Error message

duplicate StructArgs key %q

What it means

Two struct fields (or their `db` tags) resolve to the same named-argument key, making the mapping ambiguous. StructArgs rejects duplicate keys because the query could not determine which value to bind.

Solutions

1. Rename one of the colliding fields or its db tag
2. Tag one field with db:"-" to exclude it from mapping
3. Check for embedded structs that duplicate parent field names

When it happens

Trigger: Thrown at named_args.go:112 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/1fe58940d4dbf419. Report an issue: GitHub.

Appendix: source

Thrown at named_args.go:112

	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
		}

		key, ok, err := dbTagKey(sf)
		if err != nil {
			return nil, err
		}
		if !ok {
			continue
		}

		if _, exists := out[key]; exists {
			return nil, fmt.Errorf("duplicate StructArgs key %q", key)
		}

		out[key] = v.Field(i).Interface()
	}

	return out, nil
}

// dbTagKey derives the named-argument key for a struct field. Tag parsing matches
// RowToStructByName* in rows.go (structTagKey, Lookup, comma options, db:"-").
// Anonymous embedded structs are skipped without flattening (unlike row scanning).
func dbTagKey(sf reflect.StructField) (key string, ok bool, err error) {
	if sf.Anonymous {
		ft := sf.Type
		if ft.Kind() == reflect.Pointer {
			ft = ft.Elem()
		}
		if ft.Kind() == reflect.Struct {

View on GitHub (pinned to ec1a0befd2)