kataras/iris · error

unexpected tag option: %s

Error message

unexpected tag option: %s

What it means

After splitting a tag option into key=value, parseOptions only recognizes the key "name". Any other key is rejected with this error, keeping the tag grammar strict so typos fail fast at registration instead of being silently ignored.

Source

Thrown at x/sqlx/struct_row.go:88

		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. Replace the unsupported key with the supported one: only `name=...` is valid
2. Delete the unsupported option entirely
3. Use `db:"-"` if the field should not be mapped at all

Example fix

// before
ID int `db:"name=id;primary=true"`
// after
ID int `db:"name=id"`

for _, kv := range strings.Split(tag, ";") {
	parts := strings.SplitN(kv, "=", 2)
	if len(parts) == 2 && parts[0] != "name" { return fmt.Errorf("unsupported db tag option %q", parts[0]) }
}

When it happens

Trigger: A tag such as `db:"column=users"` or `db:"name=users;primary=true"` — any option key other than `name`.

Common situations: Copying tag options from GORM (`gorm:"primary_key"`) or other libraries; guessing at supported options like `type`, `primary`, `skip`.

Related errors

• option: %s: expected key value separated by '='
• 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/67a08c381413ae70. Report an issue: GitHub.