What causes "'mounts' field is missing or not an array" in ipfs/kubo?

Add a "mounts" key holding an array of mount specs, each a map with its own "mountpoint" and "child"

'mounts' field is missing or not an array

Error message

'mounts' field is missing or not an array

What it means

MountDatastoreConfig parses a mount (multi-mount) datastore spec and requires params["mounts"] to be an array of mount specs. The error is thrown when the "mounts" key is missing or its value is not []any, since there is nothing to iterate to build the mount table.

Source

Thrown at repo/fsrepo/datastores.go:104

	}
	return fun(params)
}

type mountDatastoreConfig struct {
	mounts []premount
}

type premount struct {
	ds     DatastoreConfig
	prefix ds.Key
}

// MountDatastoreConfig returns a mount DatastoreConfig from a spec.
func MountDatastoreConfig(params map[string]any) (DatastoreConfig, error) {
	var res mountDatastoreConfig
	mounts, ok := params["mounts"].([]any)
	if !ok {
		return nil, fmt.Errorf("'mounts' field is missing or not an array")
	}
	for _, iface := range mounts {
		cfg, ok := iface.(map[string]any)
		if !ok {
			return nil, fmt.Errorf("expected map for mountpoint")
		}

		child, err := AnyDatastoreConfig(cfg)
		if err != nil {
			return nil, err
		}

		prefix, found := cfg["mountpoint"]
		if !found {
			return nil, fmt.Errorf("no 'mountpoint' on mount")
		}

		res.mounts = append(res.mounts, premount{

View on GitHub (pinned to 329838acdf)

Solutions

Add a "mounts" key holding an array of mount specs, each a map with its own "mountpoint" and "child"
Fix JSON parsing so the value arrives as []any (json.Unmarshal into map[string]any gives arrays as []any)
If no mounts are needed, use a non-mount datastore type instead of an empty/invalid mounts spec

Example fix

// before
spec := map[string]any{"type": "mounts"}
// after
spec := map[string]any{"type": "mounts", "mounts": []any{
  map[string]any{"mountpoint": "/blocks", "child": map[string]any{"type": "flatfs", "path": "blocks", "sync": true}},
  map[string]any{"mountpoint": "/", "child": map[string]any{"type": "levelds", "path": "datastore"}},
}}

Defensive patterns

Strategy: validation

Validate before calling

m, ok := params["mounts"].([]any)
if !ok || len(m) == 0 { /* add a valid mounts array before calling */ }

Type guard

func mountsArray(params map[string]any) ([]any, bool) {
	m, ok := params["mounts"].([]any)
	return m, ok && len(m) > 0
}

Try / catch

ds, err := fsrepo.MountDatastoreConfig(spec)
if err != nil {
	if strings.Contains(err.Error(), "'mounts' field") {
		return fmt.Errorf("mount spec requires a mounts array: %w", err)
	}
	return err
}

Prevention

Always emit "mounts" as a JSON array of objects, never an object or string
Never leave an empty or placeholder mounts value in generated specs
Use a non-mount datastore type when only one datastore is needed

When it happens

Trigger: Calling MountDatastoreConfig(params) with params lacking "mounts", or where params["mounts"] is a string, map, or was unmarshalled into a typed struct instead of []any.

Common situations: Spec in the repo config with type "mounts" but the mounts array renamed, removed, or given as an object; manual JSON edit; a templating tool that emits an empty object instead of an array.

Related errors

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/7ce49041f977b21d. Report an issue: GitHub.