{"record":{"id":"eb1195f79e0b815d","repo":"go-sql-driver/mysql","slug":"mysql-unsupported-isolation-level-v","errorCode":null,"errorMessage":"mysql: unsupported isolation level: %v","messagePattern":"mysql: unsupported isolation level: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"utils.go","lineNumber":803,"sourceCode":"\t\t\treturn nil, errors.New(\"mysql: driver does not support the use of Named Parameters\")\n\t\t}\n\t\tdargs[n] = param.Value\n\t}\n\treturn dargs, nil\n}\n\nfunc mapIsolationLevel(level driver.IsolationLevel) (string, error) {\n\tswitch sql.IsolationLevel(level) {\n\tcase sql.LevelRepeatableRead:\n\t\treturn \"REPEATABLE READ\", nil\n\tcase sql.LevelReadCommitted:\n\t\treturn \"READ COMMITTED\", nil\n\tcase sql.LevelReadUncommitted:\n\t\treturn \"READ UNCOMMITTED\", nil\n\tcase sql.LevelSerializable:\n\t\treturn \"SERIALIZABLE\", nil\n\tdefault:\n\t\treturn \"\", fmt.Errorf(\"mysql: unsupported isolation level: %v\", level)\n\t}\n}\n","sourceCodeStart":785,"sourceCodeEnd":806,"githubUrl":"https://github.com/go-sql-driver/mysql/blob/03d76c7e07908e255ce62d126d07ede3f2365d86/utils.go#L785-L806","documentation":"Raised by mapIsolationLevel (utils.go:803) when beginning a transaction. MySQL only supports four isolation levels (READ UNCOMMITTED, READ COMMITTED, REPEATABLE READ, SERIALIZABLE); any other driver.IsolationLevel passed to sql.TxOptions falls through to this error. Called from mysqlConn.BeginTx (connection.go:623) before issuing 'SET TRANSACTION ISOLATION LEVEL'.","triggerScenarios":"Calling db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelLinearizable}) (or LevelSnapshot, or any non-default level other than the four supported ones). The error surfaces directly from BeginTx as the transaction's returned error. Note: LevelDefault is intentionally skipped before mapping, so it does not trigger this.","commonSituations":"Code ported from PostgreSQL (which supports Snapshot/Serializable-based Linearizable semantics), use of sql.LevelLinearizable (common with spanner-like APIs or test fixtures), generic transaction helpers that pass through arbitrary Isolation levels, or an ORM defaulting to an unsupported level.","solutions":["Use one of the supported levels: sql.LevelReadUncommitted, sql.LevelReadCommitted, sql.LevelRepeatableRead, or sql.LevelSerializable.","Pass sql.LevelDefault (0) to BeginTx to use the server's default isolation (REPEATABLE READ).","If you need Linearizable semantics, enforce it at the application/serialization layer, not via the MySQL driver.","Audit ORM/framework transaction config to ensure it doesn't inject an unsupported level."],"exampleFix":"// before: unsupported level\ntx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelLinearizable})\n\n// after: use a MySQL-supported level (or default)\ntx, err := db.BeginTx(ctx, &sql.TxOptions{Isolation: sql.LevelSerializable})\n// or simply\ntx, err := db.BeginTx(ctx, nil)","handlingStrategy":"validation","validationCode":"func supportedByMySQL(level sql.IsolationLevel) bool {\n    switch level {\n    case sql.LevelReadUncommitted, sql.LevelReadCommitted,\n        sql.LevelRepeatableRead, sql.LevelSerializable, sql.LevelDefault:\n        return true\n    }\n    return false\n}\n\n// before BeginTx:\nif !supportedByMySQL(opts.Isolation) {\n    opts.Isolation = sql.LevelDefault // or pick a supported level\n}","typeGuard":"func isMySQLIsolationLevel(l driver.IsolationLevel) bool {\n    switch sql.IsolationLevel(l) {\n    case sql.LevelReadUncommitted, sql.LevelReadCommitted,\n        sql.LevelRepeatableRead, sql.LevelSerializable, sql.LevelDefault:\n        return true\n    }\n    return false\n}","tryCatchPattern":"tx, err := db.BeginTx(ctx, opts)\nif err != nil && strings.Contains(err.Error(), \"unsupported isolation level\") {\n    opts.Isolation = sql.LevelDefault\n    tx, err = db.BeginTx(ctx, opts)\n}","preventionTips":["Restrict transaction code to MySQL's four supported isolation levels plus Default.","Centralize TxOptions construction so unsupported levels are rejected in one place.","When porting from PostgreSQL, drop LevelSnapshot/Linearizable usages.","Map ORMs to an explicit supported level rather than passing user input through."],"tags":["mysql","transaction","isolation-level","begin","configuration"],"backgroundTag":null,"analyzedSha":"03d76c7e07908e255ce62d126d07ede3f2365d86","analyzedAt":"2026-08-07T10:39:17.340Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}