weaviate/weaviate · error

desiredCount is limited to 1 (got %d)

Error message

desiredCount is limited to 1 (got %d)

What it means

rejectExplicitMultiShardOnNamespacedClass (invoked from AddClass) parses the shardingConfig with a maximum of 1 and rejects any class that explicitly requests desiredCount > 1 when it is not allowed (e.g. a namespaced/tenant-scoped class). Sharding is capped at one shard for such classes.

Source

Thrown at usecases/schema/class.go:279

		return nil, 0, err
	}
	return cls, version, err
}

// rejectExplicitMultiShardOnNamespacedClass rejects an explicit
// desiredCount != 1. ParseConfig with nodeCount=1 folds default and
// explicit-1 together; anything else came from the user. Parse errors
// fall through to parser.ParseClass below.
func rejectExplicitMultiShardOnNamespacedClass(shardingConfig any) error {
	if _, ok := shardingConfig.(map[string]interface{}); !ok {
		return nil
	}
	cfg, err := shardingcfg.ParseConfig(shardingConfig, 1)
	if err != nil {
		return nil
	}
	if cfg.DesiredCount != 1 {
		return fmt.Errorf("desiredCount is limited to 1 (got %d)", cfg.DesiredCount)
	}
	return nil
}

// namespaceCandidates returns the storage-candidate list for placing
// qualifiedClass's shards. On NS-disabled clusters it returns the full
// cluster candidates; on NS-enabled clusters it returns
// [namespace.home_node] so every shard pins to that one node.
func (h *Handler) namespaceCandidates(qualifiedClass string) ([]string, error) {
	if !h.config.Namespaces.Enabled {
		return h.schemaManager.StorageCandidates(), nil
	}
	ns := namespacing.NamespaceFromQualified(qualifiedClass)
	if ns == "" {
		return nil, fmt.Errorf("expected namespace-qualified class name, got %q", qualifiedClass)
	}
	got, ok := h.namespacesExister.GetNamespace(ns)
	if !ok {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Set desiredCount to 1 (or omit shardingConfig to use defaults)
2. If you need multiple shards, make the class non-namespaced (disable multi-tenancy for it)
3. Use per-tenant partitioning (multi-tenancy) instead of multi-shard for scale
4. Move large tenant data to a dedicated non-namespaced collection

Example fix

// before
"shardingConfig": {"desiredCount": 3}
// after
"shardingConfig": {"desiredCount": 1}

cfg, err := shardingcfg.ParseConfig(shardingConfig, 1)
if err != nil { return err }
if isNamespaced && cfg.DesiredCount != 1 { return fmt.Errorf("desiredCount must be 1, got %d", cfg.DesiredCount) }

_, err := client.Schema().ClassCreator().WithClass(c).Do(ctx)
if err != nil && strings.Contains(err.Error(), "desiredCount is limited to 1") {
  // drop shardingConfig or set desiredCount: 1 and retry
}

When it happens

Trigger: POST /v1/schema with a class whose shardingConfig sets desiredCount to a value greater than 1 on a class where multi-sharding is prohibited (namespaced class).

Common situations: Copying a shardingConfig from a non-namespaced collection template; raising desiredCount for scale on a multi-tenant collection; older clients importing configs written for single-tenant classes.

Related errors

• role name uses a reserved operator prefix
• namespace is required
• user IDs on namespace-enabled clusters must be namespace-pre
• reading shard state: %w
• collection is required

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/f6cec2c97692fc28. Report an issue: GitHub.