What causes "unable to use data source %s: %s" in juicedata/juicefs?

Read the wrapped cause and fix what it reports: connectivity (host/port/firewall), credentials, or DSN syntax.

unable to use data source %s: %s

Error message

unable to use data source %s: %s

What it means

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.

Source

Thrown at pkg/meta/sql.go:493

		if searchPath != "" {
			if len(strings.Split(searchPath, ",")) > 1 {
				return nil, fmt.Errorf("currently, only one schema is supported in search_path")
			}
		}
	}

	if driver == "sqlite3" {
		DirBatchNum["db"] = 4096 // SQLITE_MAX_VARIABLE_NUMBER limit
	}

	var engine *xorm.Engine
	if creator, ok := engineCreator[driver]; ok {
		engine, err = creator(addr)
	} else {
		engine, err = xorm.NewEngine(driver, addr)
	}
	if err != nil {
		return nil, fmt.Errorf("unable to use data source %s: %s", driver, err)
	}

	switch logger.Level { // make xorm less verbose
	case logrus.TraceLevel:
		engine.SetLogLevel(log.LOG_DEBUG)
	case logrus.DebugLevel:
		engine.SetLogLevel(log.LOG_INFO)
	case logrus.InfoLevel, logrus.WarnLevel:
		engine.SetLogLevel(log.LOG_WARNING)
	case logrus.ErrorLevel:
		engine.SetLogLevel(log.LOG_ERR)
	default:
		engine.SetLogLevel(log.LOG_OFF)
	}
	start := time.Now()
	if err = engine.Ping(); err != nil {
		return nil, fmt.Errorf("ping database: %s", err)
	}

View on GitHub (pinned to c9a67b23e8)

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.

Example fix

// before
--meta 'mysql://user:pass@tcp(127.0.0.1:3306)/juicefs'  # DB missing -> engine open fails
// after
mysql -e 'CREATE DATABASE IF NOT EXISTS juicefs'
--meta 'mysql://user:pass@tcp(127.0.0.1:3306)/juicefs'

Defensive patterns

Strategy: retry

Validate before calling

// preflight connectivity before mounting
db, err := sql.Open("mysql", dsn)
if err == nil {
    if err := db.Ping(); err != nil {
        return fmt.Errorf("cannot reach metadata DB: %v", err)
    }
}

Try / catch

engine, err := openEngine(driver, addr)
if err != nil {
    // transient DB/network failures: retry with backoff
    return retry.WithBackoff(3, func() error { return openEngine(driver, addr) })
}

Prevention

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.

When it happens

Trigger: `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.

Common situations: 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.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/48066172bda64b54. Report an issue: GitHub.