{"record":{"id":"c56584037bd1078b","repo":"juicedata/juicefs","slug":"ping-database-s-c56584","errorCode":null,"errorMessage":"ping database: %s","messagePattern":"ping database: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/meta/sql_mysql.go","lineNumber":78,"sourceCode":"\t}\n\n\tvar engine *xorm.Engine\n\tfor _, key := range []string{\"transaction_isolation\", \"tx_isolation\"} {\n\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":60,"sourceCodeEnd":94,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/sql_mysql.go#L60-L94","documentation":"After creating the xorm engine for MySQL, JuiceFS pings it to verify connectivity and the forced repeatable-read isolation setting. If the ping fails with any error other than 'unknown transaction isolation system variable', the engine is closed and this error wraps the ping failure — meaning the DSN parsed but the server could not be reached or rejected the connection.","triggerScenarios":"`juicefs mount mysql://...` where engine.Ping() fails: server down, wrong host/port, DNS failure, bad credentials, TLS mismatch, or the account lacking privileges (anything except an 'unknown system variable' isolation error).","commonSituations":"MySQL not running or firewall blocking 3306; wrong password; host not in MySQL grants ('Host ... is not allowed to connect'); require_secure_transport enabled without TLS configured; DNS resolution failure in containers.","solutions":["Read the wrapped message and fix the root cause — most commonly start/reach the MySQL server or correct host/port in the meta URL.","Verify credentials by connecting with mysql client from the same machine: mysql -h HOST -u USER -p.","Check MySQL grants and TLS requirements (SHOW GRANTS; require_secure_transport) and align the DSN (add tls=true or disable the requirement).","Confirm network path: ping/telnet host 3306; check k8s NetworkPolicy / security groups if applicable."],"exampleFix":"// before\njuicefs mount \"mysql://root:wrongpass@tcp(db:3306)/jfs\" /mnt/jfs\n// after — verify credentials first, then mount\nmysql -h db -u root -p   # confirm access\njuicefs mount \"mysql://root:CORRECTPASS@tcp(db:3306)/jfs\" /mnt/jfs","handlingStrategy":"validation","validationCode":"conn, err := net.DialTimeout(\"tcp\", \"db:3306\", 3*time.Second)\nif err != nil { return fmt.Errorf(\"mysql unreachable: %w\", err) }\nconn.Close()","typeGuard":null,"tryCatchPattern":"if err := mountVol(); err != nil && strings.Contains(err.Error(), \"ping database\") {\n    log.Fatalf(\"check MySQL server, credentials, grants, and network: %v\", err)\n}","preventionTips":["Health-check MySQL reachability before mounting (telnet/tcp probe)","Grant the JuiceFS user access from the client host in MySQL","Align TLS settings (require_secure_transport vs DSN tls param)","Use retries/readiness probes in k8s before the mount container starts"],"tags":["mysql","database","connectivity","startup","network"],"backgroundTag":"connection-refused","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}