juicedata/juicefs · critical

ping database: %s

Error message

ping database: %s

What it means

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.

Source

Thrown at pkg/meta/sql_mysql.go:78

	}

	var engine *xorm.Engine
	for _, key := range []string{"transaction_isolation", "tx_isolation"} {
		cfg.Params[key] = "'repeatable-read'"
		engine, err = xorm.NewEngine("mysql", cfg.FormatDSN())
		if err != nil {
			return nil, fmt.Errorf("unable to create engine: %s", err)
		}

		if err = engine.Ping(); err == nil {
			return engine, nil
		}

		_ = engine.Close()
		delete(cfg.Params, key)

		if !isUnknownTransactionIsolationErr(err, key) {
			return nil, fmt.Errorf("ping database: %s", err)
		}
	}

	return nil, fmt.Errorf("failed to set isolation level: %s", err)
}

func isUnknownTransactionIsolationErr(err error, key string) bool {
	return err != nil && strings.Contains(strings.ToLower(err.Error()), fmt.Sprintf("unknown system variable '%s'", key))
}

func init() {
	dupErrorCheckers = append(dupErrorCheckers, isMySQLDuplicateEntryErr)
	engineCreator["mysql"] = createMySQLEngine
	Register("mysql", newSQLMeta)
}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Read the wrapped message and fix the root cause — most commonly start/reach the MySQL server or correct host/port in the meta URL.
2. Verify credentials by connecting with mysql client from the same machine: mysql -h HOST -u USER -p.
3. Check MySQL grants and TLS requirements (SHOW GRANTS; require_secure_transport) and align the DSN (add tls=true or disable the requirement).
4. Confirm network path: ping/telnet host 3306; check k8s NetworkPolicy / security groups if applicable.

Example fix

// before
juicefs mount "mysql://root:wrongpass@tcp(db:3306)/jfs" /mnt/jfs
// after — verify credentials first, then mount
mysql -h db -u root -p   # confirm access
juicefs mount "mysql://root:CORRECTPASS@tcp(db:3306)/jfs" /mnt/jfs

conn, err := net.DialTimeout("tcp", "db:3306", 3*time.Second)
if err != nil { return fmt.Errorf("mysql unreachable: %w", err) }
conn.Close()

if err := mountVol(); err != nil && strings.Contains(err.Error(), "ping database") {
    log.Fatalf("check MySQL server, credentials, grants, and network: %v", err)
}

When it happens

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

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

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

• ping database: %s
• unable to create engine: %s
• failed to set isolation level: %s
• unable to use data source %s: %s
• create table delegationToken: %s

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