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

URL-encode special characters in username/password (e.g. percent-encode `@` as `%40`).

parse url %s failed: %s

Error message

parse url %s failed: %s

What it means

When the metadata driver is postgres, JuiceFS rewrites the address into a `postgres://...` URL, switches to the pgx driver, and parses it with net/url.Parse to extract search_path. If the address cannot be parsed as a URL (malformed scheme, invalid characters, bad host/port syntax), NewClient fails with this error before any database connection is attempted.

Source

Thrown at pkg/meta/sql.go:472

		}
		if !query.Has("_timeout") && !query.Has("_busy_timeout") {
			query.Add("_timeout", "5000")
		}
	}

	if encode := query.Encode(); encode != "" {
		addr = fmt.Sprintf("%s?%s", baseUrl, encode)
	} else {
		addr = baseUrl
	}

	if driver == "postgres" {
		addr = driver + "://" + addr
		driver = "pgx"

		parse, err := url.Parse(addr)
		if err != nil {
			return nil, fmt.Errorf("parse url %s failed: %s", addr, 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")
			}
		}
	}

	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)

View on GitHub (pinned to c9a67b23e8)

Solutions

URL-encode special characters in username/password (e.g. percent-encode `@` as `%40`).
Verify URL syntax: `postgres://user:password@host:port/dbname?param=value`.
Simplify to a minimal URL (`postgres://host/db`) and add parts back until the failure reproduces.
Move credentials out of the URL (PGPASSWORD, ~/.pgpass) if they contain awkward characters.

Example fix

// before
--meta 'postgres://user:p@ss@host:5432/db'
// after
--meta 'postgres://user:p%40ss@host:5432/db'

Defensive patterns

Strategy: validation

Validate before calling

// validate the postgres URL before passing it to JuiceFS
u, err := url.Parse(metaURL)
if err != nil || u.Scheme == "" || u.Host == "" {
    return fmt.Errorf("invalid postgres meta URL %q: %v", metaURL, err)
}

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "parse url") {
        // re-encode credentials and retry once
    }
}

Prevention

Percent-encode every credential character (use url.UserPassword / url.QueryEscape in Go).
Never build metadata URLs by raw string concatenation.
Sanity-check the URL with url.Parse or an equivalent parser before deployment.
Avoid spaces and stray `%` characters in the URL.

When it happens

Trigger: `juicefs format`/`mount` with `--meta 'postgres://...'` where the host:port/credential portion is malformed so url.Parse fails, or an unescaped special character (space, raw `%`, unpaired `@`) appears in the credentials or query string.

Common situations: Passwords containing `@`, `:`, `/`, or `%` that are not URL-encoded; spaces in the URL; missing host; typos like double `://`; building the URL by string concatenation without escaping.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

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