go-sql-driver/mysql · error

unknown field type %d

Error message

unknown field type %d

What it means

While decoding a binary-protocol result row (packets.go:1446), a column's fieldType byte does not match any type the driver knows how to decode. The surrounding code comment 'Please report if this happens!' signals a column type the driver version has not implemented, typically from a newer server feature (e.g. a vector type) or a non-MySQL-compatible server, or corrupted packet data.

Source

Thrown at packets.go:1446

						return fmt.Errorf(
							"protocol error, illegal decimals value %d",
							rows.rs.columns[i].decimals,
						)
					}
				}
				dest[i], err = formatBinaryDateTime(data[pos:pos+int(num)], dstlen)
			}

			if err == nil {
				pos += int(num)
				continue
			} else {
				return err
			}

		// Please report if this happens!
		default:
			return fmt.Errorf("unknown field type %d", rows.rs.columns[i].fieldType)
		}
	}

	return nil
}

View on GitHub (pinned to c426bd9379)

Solutions

1. Upgrade the go-sql-driver/mysql package to the latest release.
2. Cast the unknown column to a supported type in SQL: SELECT CAST(col AS CHAR) AS col.
3. Exclude the unsupported column from the query.
4. If the type is genuinely unsupported, report it upstream with the server version.

Example fix

// before — 'embedding' uses a type the driver cannot decode
rows, _ := db.Query("SELECT embedding FROM docs")

// after
rows, _ := db.Query("SELECT CAST(embedding AS CHAR) AS embedding FROM docs")

if err := rows.Scan(dest...); err != nil {
    if strings.Contains(err.Error(), "unknown field type") {
        // driver cannot decode this column; upgrade the driver or CAST the column in SQL
    }
}

When it happens

Trigger: Selecting a column whose type code predates support in the installed driver version (e.g. HeatWave/vector columns on an older driver); a non-MySQL server returning an unrecognized type code; packet corruption altering the field type byte.

Common situations: Old driver version against a newer MySQL with novel column types; selecting VECTOR or another exotic type directly; a MariaDB-fork-specific type not in the map.

Related errors

• protocol error, illegal decimals value %d
• MySQL server does not support required protocol 41+
• commands out of sync. You can't run this command now
• commands out of sync. Did you run multiple statements at onc
• invalid time bytes: %s

AI-assisted analysis of go-sql-driver/mysql@c426bd9379 (2026-08-04). Data as JSON: /data/errors/3cb380721afa74e1.json. Report an issue: GitHub.