kataras/iris · error

option: %s: expected key value separated by '='

Error message

option: %s: expected key value separated by '='

What it means

parseOptions parses a struct tag's option string into name/value pairs and expects each option to be `key=value`. An option containing more than one '=' (kv length > 2) cannot be split unambiguously and triggers this error. Tag names with no options (single token) are handled earlier as the column name.

Source

Thrown at x/sqlx/struct_row.go:81

func parseOptions(fieldTag string, c *Column) error {
	options := strings.Split(fieldTag, ",")
	for _, opt := range options {
		if opt == "" {
			continue // skip empty.
		}

		var key, value string

		kv := strings.Split(opt, "=") // When more options come to play.
		switch len(kv) {
		case 2:
			key = kv[0]
			value = kv[1]
		case 1:
			c.Name = kv[0]
			return nil
		default:
			return fmt.Errorf("option: %s: expected key value separated by '='", opt)
		}

		switch key {
		case "name":
			c.Name = value
		default:
			return fmt.Errorf("unexpected tag option: %s", key)
		}
	}

	return nil
}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Rewrite the option with exactly one '=': `db:"name=users"`
2. Remove the extra '=value' portion or quote/encode it in a supported way
3. Simplify the tag to just the column name if no options are needed

Example fix

// before
Field string `db:"name=user=name"`
// after
Field string `db:"name=user_name"`

for _, opt := range strings.Split(tag, ";") {
	if strings.Count(opt, "=") > 1 { return fmt.Errorf("tag option %q has multiple '='", opt) }
}

When it happens

Trigger: A db tag like `db:"name=user=name"` or `db:"name=x=y"` — an option value that itself contains '='.

Common situations: Typos where '=' was typed twice; pasting options from another ORM syntax; accidental inclusion of SQL expressions in the tag.

Related errors

• unexpected tag option: %s
• convert struct: field name: %q: %w
• multipart related: next part: %w
• redirect match: status code digits: %s: %v
• sqlx: bind: unregistered type: %q

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