juicedata/juicefs · error

invalid storage: %s

Error message

invalid storage: %s

What it means

CreateStorage looks up the storage backend constructor in a registry keyed by the storage name (s3, oss, cos, minio, nfs, ...). If the name is not registered, it returns 'invalid storage: <name>'. This is a typo/unsupported-backend guard, thrown before any network call.

Source

Thrown at pkg/object/object_storage.go:202

var storages = make(map[string]Creator)

func Register(name string, register Creator) {
	storages[name] = register
}

func IsSupported(name string) bool {
	_, ok := storages[name]
	return ok
}

func CreateStorage(name, endpoint, accessKey, secretKey, token string) (ObjectStorage, error) {
	f, ok := storages[name]
	if ok {
		logger.Debugf("Creating %s storage at endpoint %s", name, endpoint)
		return f(endpoint, accessKey, secretKey, token)
	}
	return nil, fmt.Errorf("invalid storage: %s", name)
}

var bufPool = sync.Pool{
	New: func() interface{} {
		// Default io.Copy uses 32KB buffer, here we choose a larger one (1MiB io-size increases throughput by ~20%)
		buf := make([]byte, 1<<20)
		return &buf
	},
}

type listThread struct {
	sync.Mutex
	cond      *utils.Cond
	ready     bool
	err       error
	entries   []Object
	nextToken string
	hasMore   bool

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Check the exact supported storage names in pkg/object/object_storage.go (the storages map) and fix the spelling
2. Rebuild with the full build (not juicefs.lite) if the backend was compiled out
3. Upgrade JuiceFS if the backend name is newer than your binary
4. Validate the --storage value before calling CreateStorage

Example fix

// before
store, err := object.CreateStorage("S3", endpoint, ak, sk, "")
// after
store, err := object.CreateStorage("s3", endpoint, ak, sk, "")

supported := map[string]bool{"s3":true,"oss":true,"cos":true,"obs":true,"minio":true,"nfs":true}
if !supported[name] { return fmt.Errorf("unsupported storage %q", name) }

store, err := object.CreateStorage(name, endpoint, ak, sk, token)
if err != nil {
	var ie *fmt.Errorf
	if strings.HasPrefix(err.Error(), "invalid storage:") {
		// fall back to a known-good backend name
	}
}

When it happens

Trigger: Passing an unknown or misspelled storage name as the first argument of CreateStorage, or a name whose backend was compiled out (e.g. juicefs.lite builds disable most object storages), or via --storage flag with an unsupported value.

Common situations: Typos like 'S3' vs 's3' or 'cephs' vs 'cephs3'; using a backend not compiled into a lite binary; older JuiceFS version lacking a newer backend name; format/storage config mismatch.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• object storage: %s
• Invalid endpoint: %v, error: %v
• Invalid endpoint: %v
• Invalid endpoint %s: %s
• Can't read default config file: %s

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