kataras/iris · error

sqlx: register: %q: %s

Error message

sqlx: register: %q: %s

What it means

Register reflects over the struct to derive columns via convertStructToColumns; if that fails (e.g. unsupported struct shape) it panics with the value's type and the underlying error, prefixed 'sqlx: register:'.

Source

Thrown at x/sqlx/sqlx.go:86

// Register caches a struct value to the schema.
func (s *Schema) Register(tableName string, value any) *Schema {
	typ := reflect.TypeOf(value)
	for typ.Kind() == reflect.Ptr {
		typ = typ.Elem()
	}

	if tableName == "" {
		// convert to a human name, e.g. sqlx.Food -> food.
		typeName := typ.String()
		if idx := strings.LastIndexByte(typeName, '.'); idx > 0 && len(typeName) > idx {
			typeName = typeName[idx+1:]
		}
		tableName = snakeCase(typeName)
	}

	columns, err := convertStructToColumns(typ, s.ColumnNameFunc)
	if err != nil {
		panic(fmt.Sprintf("sqlx: register: %q: %s", reflect.TypeOf(value).String(), err.Error()))
	}

	s.Rows[typ] = &Row{
		Schema:     s.Name,
		Name:       tableName,
		StructType: typ,
		Columns:    columns,
	}

	return s
}

// Query is a shortcut of executing a query and bind the result to "dst".
func (s *Schema) Query(ctx context.Context, db *sql.DB, dst any, query string, args ...any) error {
	rows, err := db.QueryContext(ctx, query, args...)
	if err != nil {
		return err
	}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Ensure the registered type has at least one exported field usable as a column
2. Check the custom ColumnNameFunc doesn't produce empty/invalid names
3. Log/handle the error by recovering around Register at startup

Example fix

// before
type user struct {
    name string // unexported
}
db.Register(user{})
// after
type User struct {
    Name string `db:"name"`
}
db.Register(User{})

func registrable(v any) bool {
    t := reflect.TypeOf(v)
    if t.Kind() != reflect.Struct { return false }
    for i := 0; i < t.NumField(); i++ {
        if t.Field(i).PkgPath == "" { return true } // has exported field
    }
    return false
}

defer func() { if r := recover(); r != nil { log.Fatalf("sqlx register failed: %v", r) } }()
db.Register(Model{})

When it happens

Trigger: Calling s.Register(value) with a struct that convertStructToColumns cannot process — typically a struct with no exportable/valid columns or a field configuration error under the configured ColumnNameFunc.

Common situations: Registering an empty struct, a struct with only unexported fields, or a misconfigured custom ColumnNameFunc producing invalid column names.

Related errors

• sqlx: bind: destination not a pointer
• bindings: unresolved: no a func type: %#+v
• bindings: unresolved: not a struct type: %#+v
• struct: method: %s does not exist
• on field index: %d: %v

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