What causes "parse url %s failed: %s" in juicedata/juicefs?

Percent-encode special characters in user/password: use url.QueryEscape or the escape function JuiceFS provides, e.g. 'postgres://user:p%40ss@host/db'.

juicedata/juicefs · error

parse url %s failed: %s

Error message

parse url %s failed: %s

What it means

newSQLStore parses the metadata URL with net/url.Parse after normalizing postgres-style addresses to 'postgres://...'. If the string is not a valid URL (bad characters, malformed host/percent-encoding), construction of the SQL object store fails before any database connection is attempted.

Source

Thrown at pkg/object/sql.go:175

		}
	}
	return generateListResult(objs, limit)
}

func newSQLStore(driver, addr, user, password string) (ObjectStorage, error) {
	var err error
	uri := addr
	if user != "" {
		uri = user + ":" + password + "@" + addr
	}
	var searchPath string
	if driver == "postgres" {
		uri = "postgres://" + uri
		driver = "pgx"

		parse, err := url.Parse(uri)
		if err != nil {
			return nil, fmt.Errorf("parse url %s failed: %s", uri, err)
		}
		searchPath = parse.Query().Get("search_path")
		if searchPath != "" {
			if len(strings.Split(searchPath, ",")) > 1 {
				return nil, fmt.Errorf("currently, only one schema is supported in search_path")
			}
		}
	}
	engine, err := xorm.NewEngine(driver, uri)
	if err != nil {
		return nil, fmt.Errorf("open %s: %s", uri, 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:

View on GitHub (pinned to c9a67b23e8)

Solutions

Percent-encode special characters in user/password: use url.QueryEscape or the escape function JuiceFS provides, e.g. 'postgres://user:p%40ss@host/db'.
Verify the URL has scheme, host, and database in proper form: postgres://user:password@host:port/dbname?params.
Trim whitespace and remove stray quotes/brackets from the metadata URL.

Example fix

// before
meta := "postgres://juicefs:p@ssw@rd@127.0.0.1:5432/jfs"
// after (percent-encode '@' in password)
meta := "postgres://juicefs:p%40ssw%40rd@127.0.0.1:5432/jfs"

Defensive patterns

Strategy: validation

Validate before calling

u, err := url.Parse(metaURL)
if err != nil {
    return fmt.Errorf("invalid metadata URL: %v", err)
}

Try / catch

store, err := newSQLStore(ctx, "postgres", addr, ak, sk)
if err != nil && strings.HasPrefix(err.Error(), "parse url") {
    return fmt.Errorf("percent-encode special chars in the metadata URL: %w", err)
}

Prevention

Percent-encode username/password with url.QueryEscape or juicefs escape before composing the URL.
Keep the metadata URL in a config file and validate it with url.Parse at startup.
Avoid copy-pasting connection strings with shell artifacts (quotes, whitespace).

When it happens

Trigger: Passing a metadata address like 'postgres://user:pa ss@host/db', an address with unescaped special characters ('%', spaces, control chars), or otherwise unparseable URL syntax for a postgres driver store.

Common situations: Special characters in the database password that are not percent-encoded (e.g. @, /, #, space) when building the JuiceFS metadata URL; copying a connection string with surrounding whitespace or brackets.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

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