What causes "convert struct: field name: %q: %w" in kataras/iris?

Fix the tag on the named field to valid syntax (name=xxx, semicolon-separated options)

convert struct: field name: %q: %w

Error message

convert struct: field name: %q: %w

What it means

While converting each struct field to a column, a per-field error (usually from parsing the struct tag options) is wrapped with the offending field name via %w. This pinpoints which field's tag is malformed. Registration fails entirely when any field tag cannot be parsed.

Source

Thrown at x/sqlx/struct_row.go:33

type ColumnNameFunc = func(string) string

func convertStructToColumns(typ reflect.Type, nameFunc ColumnNameFunc) (map[string]*Column, error) {
	if kind := typ.Kind(); kind != reflect.Struct {
		return nil, fmt.Errorf("convert struct: invalid type: expected a struct value but got: %q", kind.String())
	}

	// Retrieve only fields valid for database.
	fields := reflex.LookupFields(typ, "")

	columns := make(map[string]*Column, len(fields))
	for i, field := range fields {
		column, ok, err := convertStructFieldToColumn(field, DefaultTag, nameFunc)
		if !ok {
			continue
		}

		if err != nil {
			return nil, fmt.Errorf("convert struct: field name: %q: %w", field.Name, err)
		}

		column.Index = i
		columns[column.Name] = column
	}

	return columns, nil
}

func convertStructFieldToColumn(field reflect.StructField, optionalTag string, nameFunc ColumnNameFunc) (*Column, bool, error) {
	c := &Column{
		Name:       nameFunc(field.Name),
		FieldIndex: field.Index,
	}

	fieldTag, ok := field.Tag.Lookup(optionalTag)
	if ok {
		if fieldTag == "-" {

View on GitHub (pinned to 7bedaf55a0)

Solutions

Fix the tag on the named field to valid syntax (name=xxx, semicolon-separated options)
Remove unsupported options from the tag
Use `db:"-"` to exclude the field from mapping if it needs no column

Example fix

// before
Name string `db:"name:users,primary"`
// after
Name string `db:"name=users"`

Defensive patterns

Strategy: validation

Validate before calling

for _, f := range reflect.VisibleFields(reflect.TypeOf(Model{})) {
	tag := f.Tag.Get("db")
	if tag != "" && tag != "-" && strings.Contains(tag, ",") { return fmt.Errorf("field %s: suspicious tag %q", f.Name, tag) }
}

Prevention

Keep db tags to `name=xxx` form or plain column name
Use `db:"-"` to exclude fields
Add a startup test that registers every model struct

When it happens

Trigger: Register on a struct where one field's tag contains options that parseOptions rejects, e.g. `db:"name:users,extra"` (malformed separator) or multiple '=' parts.

Common situations: Hand-written tags with typos (comma instead of semicolon, missing '='); copying tags from other ORMs with different option syntaxes.

Related errors

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/94c707b8682cc451. Report an issue: GitHub.