{"record":{"id":"48066172bda64b54","repo":"juicedata/juicefs","slug":"unable-to-use-data-source-s-s","errorCode":null,"errorMessage":"unable to use data source %s: %s","messagePattern":"unable to use data source (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"pkg/meta/sql.go","lineNumber":493,"sourceCode":"\t\tif searchPath != \"\" {\n\t\t\tif len(strings.Split(searchPath, \",\")) > 1 {\n\t\t\t\treturn nil, fmt.Errorf(\"currently, only one schema is supported in search_path\")\n\t\t\t}\n\t\t}\n\t}\n\n\tif driver == \"sqlite3\" {\n\t\tDirBatchNum[\"db\"] = 4096 // SQLITE_MAX_VARIABLE_NUMBER limit\n\t}\n\n\tvar engine *xorm.Engine\n\tif creator, ok := engineCreator[driver]; ok {\n\t\tengine, err = creator(addr)\n\t} else {\n\t\tengine, err = xorm.NewEngine(driver, addr)\n\t}\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to use data source %s: %s\", driver, err)\n\t}\n\n\tswitch logger.Level { // make xorm less verbose\n\tcase logrus.TraceLevel:\n\t\tengine.SetLogLevel(log.LOG_DEBUG)\n\tcase logrus.DebugLevel:\n\t\tengine.SetLogLevel(log.LOG_INFO)\n\tcase logrus.InfoLevel, logrus.WarnLevel:\n\t\tengine.SetLogLevel(log.LOG_WARNING)\n\tcase logrus.ErrorLevel:\n\t\tengine.SetLogLevel(log.LOG_ERR)\n\tdefault:\n\t\tengine.SetLogLevel(log.LOG_OFF)\n\t}\n\tstart := time.Now()\n\tif err = engine.Ping(); err != nil {\n\t\treturn nil, fmt.Errorf(\"ping database: %s\", err)\n\t}","sourceCodeStart":475,"sourceCodeEnd":511,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/sql.go#L475-L511","documentation":"After choosing an engine creator (or falling back to xorm.NewEngine) for the given SQL driver, JuiceFS attempts to open/initialize the database engine. Any failure returned by the driver (bad DSN, unreachable host, nonexistent database, unreadable SQLite path, unknown driver) is wrapped as this error naming the driver and underlying cause.","triggerScenarios":"`juicefs format`/`mount` with a SQL --meta URL (mysql, postgres/pgx, sqlite3) where the driver cannot open the data source: wrong host/port, database not created, unreadable sqlite file path, unsupported DSN syntax, or an unknown driver string.","commonSituations":"Database server down or DNS not resolving; MySQL database not created before formatting (`CREATE DATABASE juicefs`); SQLite file in a nonexistent or non-writable directory; wrong credentials; juicefs.lite builds with drivers compiled out.","solutions":["Read the wrapped cause and fix what it reports: connectivity (host/port/firewall), credentials, or DSN syntax.","For MySQL, create the database first: `mysql -e 'CREATE DATABASE juicefs'` then retry the format.","For SQLite, verify the file's directory exists and is writable and the URL path is correct.","Confirm the driver in the URL is mysql, postgres/pg, or sqlite3 and that your binary includes it (full build, not juicefs.lite).","Preflight the connection with `mysql -h host -u user -p` or `psql 'postgres://...'` using the same credentials."],"exampleFix":"// before\n--meta 'mysql://user:pass@tcp(127.0.0.1:3306)/juicefs'  # DB missing -> engine open fails\n// after\nmysql -e 'CREATE DATABASE IF NOT EXISTS juicefs'\n--meta 'mysql://user:pass@tcp(127.0.0.1:3306)/juicefs'","handlingStrategy":"retry","validationCode":"// preflight connectivity before mounting\ndb, err := sql.Open(\"mysql\", dsn)\nif err == nil {\n    if err := db.Ping(); err != nil {\n        return fmt.Errorf(\"cannot reach metadata DB: %v\", err)\n    }\n}","typeGuard":null,"tryCatchPattern":"engine, err := openEngine(driver, addr)\nif err != nil {\n    // transient DB/network failures: retry with backoff\n    return retry.WithBackoff(3, func() error { return openEngine(driver, addr) })\n}","preventionTips":["Create the database/schema (MySQL) before running `juicefs format`.","Preflight the connection with the mysql/psql CLI using the same credentials and host.","Ensure SQLite directories exist and are writable before pointing a meta URL at them.","Wrap startup in a health-check/retry since transient network failures surface here.","Run a full (non-lite) build if the driver you need is compiled out."],"tags":["go","database","connection","xorm","mysql","postgres","sqlite"],"backgroundTag":"database-query-failed","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"}