What causes "failed to parse value as int: %v" in juicedata/juicefs?

Correct the metadata URL query parameter to a valid integer value (e.g. `?batch_num=100`).

failed to parse value as int: %v

Error message

failed to parse value as int: %v

What it means

extractCustomConfig is a generic helper in JuiceFS's SQL metadata engine (pkg/meta/sql.go) that reads a custom query parameter from the metadata URL. When the expected value type is int, the raw string from the URL is converted with strconv.Atoi; if the user supplied a non-numeric value, the conversion fails and this error is returned so the metadata URL is rejected before a client is created.

Source

Thrown at pkg/meta/sql.go:305

	node    map[Ino]*node
	symlink map[Ino]*symlink
	xattr   map[Ino][]*xattr
	edges   map[Ino][]*edge
	chunk   map[string]*chunk
}

func extractCustomConfig[T string | int](value *url.Values, key string, defaultV T) (T, error) {
	if value == nil {
		return defaultV, nil
	}
	if v := value.Get(key); v != "" {
		value.Del(key)
		var result T
		switch any(defaultV).(type) {
		case int:
			parsedInt, err := strconv.Atoi(v)
			if err != nil {
				return defaultV, fmt.Errorf("failed to parse value as int: %v", err)
			}
			result = any(parsedInt).(T)
		case string:
			result = any(v).(T)
		default:
			return defaultV, fmt.Errorf("unsupported type: %T", defaultV)
		}
		return result, nil
	} else {
		return defaultV, nil
	}
}

type prefixMapper struct {
	mapper names.Mapper
	prefix string
}

View on GitHub (pinned to c9a67b23e8)

Solutions

Correct the metadata URL query parameter to a valid integer value (e.g. `?batch_num=100`).
Check the JuiceFS docs/source for the exact parameter name and expected type of each custom SQL-engine setting.
Remove the invalid parameter entirely so the built-in default is used.
Retry `juicefs format`/`mount` with the corrected --meta URL.

Example fix

// before
--meta 'mysql://user:pass@host:3306/db?batch_num=abc'
// after
--meta 'mysql://user:pass@host:3306/db?batch_num=100'

Defensive patterns

Strategy: validation

Validate before calling

// validate before handing the meta URL to JuiceFS
n, err := strconv.Atoi(vals.Get("batch_num"))
if err != nil {
    return fmt.Errorf("batch_num must be an integer, got %q", vals.Get("batch_num"))
}
_ = n

Try / catch

if err != nil {
    if strings.Contains(err.Error(), "failed to parse value as int") {
        // fall back to default config or exit with a clear message
    }
}

Prevention

Validate all custom query parameters with strconv before building the meta URL.
Keep documented parameter names/types in a reference table and review mount commands against it.
Quote the whole --meta argument in shell scripts to avoid mangling values.
Test the exact URL with `juicefs format` before production rollout.

When it happens

Trigger: Creating a dbMeta client with a SQL metadata URL (MySQL/PostgreSQL/SQLite) whose custom query parameters include a key consumed as an int by extractCustomConfig, but whose value is not a valid integer (e.g. `?batch_num=abc`).

Common situations: Typos in the --meta URL, quoting mistakes that turn numbers into strings, copy-pasted URLs with invalid query values, shell quoting mangling digits, or users guessing undocumented parameter names/types.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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