What causes "unknown field type %d" in go-sql-driver/mysql?

Verify the server/proxy is MySQL/MariaDB-protocol-conformant.

unknown field type

Error message

unknown field type %d

What it means

The result-row decoder switches on each column's MySQL field-type code; an unrecognized code falls through to the default. The source comment says 'Please report if this happens!' - it is not expected with compliant servers.

Solutions

Verify the server/proxy is MySQL/MariaDB-protocol-conformant.
Retry once (transient corruption).
Upgrade the go-sql-driver/mysql to a version that supports the field type.
Report upstream with the field-type number if it reproduces against a compliant server.

Example fix

null

Defensive patterns

Strategy: validation

Validate before calling

// Not caller-validatable; keep the driver current and the server conformant.

Type guard

null

Try / catch

// Returned from rows.Next()/Scan; retry or surface to the user.
for rows.Next() {
    if err := rows.Scan(...); err != nil && strings.Contains(err.Error(), "unknown field type") {
        // upgrade driver / verify server; retry or report
    }
}

Prevention

Keep go-sql-driver/mysql up to date for new field types.
Use MySQL/MariaDB-conformant servers and proxies.
Retry transient decoding errors once before escalating.

When it happens

Trigger: A server/proxy returning a column with a field-type code the driver does not handle; packet corruption shifting bytes so the type byte is wrong; a newer MySQL introducing a field type the driver version predates.

Common situations: Non-MySQL-compatible servers or proxies; corrupted packets; a driver version older than the server's new data types.

Related errors

AI-assisted analysis of go-sql-driver/mysql@03d76c7e07 (2026-08-07). Data as JSON: /api/errors/3cb380721afa74e1. Report an issue: GitHub.

Appendix: 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 03d76c7e07)