{"record":{"id":"ed164961612dfbbe","repo":"juicedata/juicefs","slug":"failed-to-set-isolation-level-s","errorCode":null,"errorMessage":"failed to set isolation level: %s","messagePattern":"failed to set isolation level: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/meta/sql_mysql.go","lineNumber":82,"sourceCode":"\t\tcfg.Params[key] = \"'repeatable-read'\"\n\t\tengine, err = xorm.NewEngine(\"mysql\", cfg.FormatDSN())\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"unable to create engine: %s\", err)\n\t\t}\n\n\t\tif err = engine.Ping(); err == nil {\n\t\t\treturn engine, nil\n\t\t}\n\n\t\t_ = engine.Close()\n\t\tdelete(cfg.Params, key)\n\n\t\tif !isUnknownTransactionIsolationErr(err, key) {\n\t\t\treturn nil, fmt.Errorf(\"ping database: %s\", err)\n\t\t}\n\t}\n\n\treturn nil, fmt.Errorf(\"failed to set isolation level: %s\", err)\n}\n\nfunc isUnknownTransactionIsolationErr(err error, key string) bool {\n\treturn err != nil && strings.Contains(strings.ToLower(err.Error()), fmt.Sprintf(\"unknown system variable '%s'\", key))\n}\n\nfunc init() {\n\tdupErrorCheckers = append(dupErrorCheckers, isMySQLDuplicateEntryErr)\n\tengineCreator[\"mysql\"] = createMySQLEngine\n\tRegister(\"mysql\", newSQLMeta)\n}\n","sourceCodeStart":64,"sourceCodeEnd":94,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/sql_mysql.go#L64-L94","documentation":"JuiceFS requires MySQL's isolation level to be settable to repeatable-read and probes with two system variable names (transaction_isolation for MySQL 5.7+/8.x, tx_isolation for older). If every probe's ping failed with 'unknown system variable' for all candidate keys, it gives up with this error, meaning the server is a dialect that supports neither variable or errors unexpectedly.","triggerScenarios":"Connecting to a MySQL-compatible server that rejects both `transaction_isolation` and `tx_isolation` system variables — e.g. certain proxies (ProxySQL variants), MariaDB forks, or serverless MySQL gateways that strip system variables.","commonSituations":"Pointing JuiceFS at an aggressive MySQL proxy or managed service that doesn't expose isolation variables; a custom middleware rewriting the handshake; very old or heavily modified MySQL builds.","solutions":["Connect directly to a real MySQL (or MariaDB ≥5.7 with tx_isolation) server instead of through the proxy that hides system variables.","Verify with mysql client: SHOW VARIABLES LIKE 'tx_isolation'; and SHOW VARIABLES LIKE 'transaction_isolation'; — one must exist.","Check the wrapped error text: it shows the last 'unknown system variable' message; confirm which dialect the server actually is.","If the proxy is required, configure it to pass through system-variable queries, or use a JuiceFS metadata engine that doesn't need this (redis/sqlite)."],"exampleFix":"// before (proxy strips system variables)\njuicefs mount \"mysql://user:pass@tcp(proxy:6033)/jfs\" /mnt/jfs\n// after (point at the real MySQL backend)\njuicefs mount \"mysql://user:pass@tcp(mysql-primary:3306)/jfs\" /mnt/jfs","handlingStrategy":"fallback","validationCode":"out, _ := exec.Command(\"mysql\", \"-h\", host, \"-u\", user, \"-p\"+pw, \"-e\", \"SHOW VARIABLES LIKE 'tx_isolation'; SHOW VARIABLES LIKE 'transaction_isolation';\").Output()\nif len(out) == 0 { return fmt.Errorf(\"server exposes neither isolation variable; use a direct MySQL backend\") }","typeGuard":null,"tryCatchPattern":"if err := mountVol(); err != nil && strings.Contains(err.Error(), \"failed to set isolation level\") {\n    log.Fatalf(\"server does not expose isolation variables — bypass proxy or switch engine: %v\", err)\n}","preventionTips":["Point JuiceFS at a real MySQL/MariaDB server, not a system-variable-stripping proxy","Check SHOW VARIABLES for tx_isolation/transaction_isolation before onboarding a metadata host","Fall back to redis/sqlite engines for restricted MySQL-compatible services"],"tags":["mysql","database","isolation-level","compatibility","startup"],"backgroundTag":"unsupported-config-value","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}