weaviate/weaviate · error

unable to retrieve shards for class %s

Error message

unable to retrieve shards for class %s

What it means

newFileMatcher lists each class's shards via schemaReader.Shards(className); failure here is reported with this (unwrapped) message. Note the underlying error is not chained, so logs will show only that shards for the class could not be retrieved.

Source

Thrown at usecases/schema/migrate/fs/file_structure_migration.go:174

}

type schemaReader interface {
	Shards(class string) ([]string, error)
	ReadOnlySchema() models.Schema
}

func newFileMatcher(schemaReader schemaReader, rootPath string) (*fileMatcher, error) {
	shardLsmDirs := make(map[string]*classShard)
	shardFilePrefixes := make(map[string]*classShard)
	shardGeoDirPrefixes := make(map[string]*classShardGeoProp)
	classes := make(map[string][]*classShard)

	schema := schemaReader.ReadOnlySchema()
	for _, class := range schema.Classes {
		className := class.Class
		shards, err := schemaReader.Shards(className)
		if err != nil {
			return nil, fmt.Errorf("unable to retrieve shards for class %s", className)
		}
		lowercasedClass := strings.ToLower(class.Class)

		var geoProps []string
		for _, prop := range class.Properties {
			if dt, ok := entschema.AsPrimitive(prop.DataType); ok && dt == entschema.DataTypeGeoCoordinates {
				geoProps = append(geoProps, prop.Name)
			}
		}

		classes[class.Class] = make([]*classShard, 0, len(shards))
		for _, shard := range shards {
			cs := &classShard{class: class.Class, shard: shard}
			shardLsmDirs[fmt.Sprintf("%s_%s_lsm", lowercasedClass, shard)] = cs
			shardFilePrefixes[fmt.Sprintf("%s_%s", lowercasedClass, shard)] = cs
			classes[class.Class] = append(classes[class.Class], cs)

			for _, geoProp := range geoProps {

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Inspect the weaviate logs preceding this error for the underlying schema read failure
2. Verify the schema files in the data directory are not corrupt (compare with backup)
3. Restart weaviate to re-attempt schema load before migration
4. Remove the broken class from the schema or restore schema from backup

// ensure the schema loads and Shards() works for every class before enabling migration

if err := migrate(); err != nil {
  if strings.Contains(err.Error(), "unable to retrieve shards for class") {
    // restore schema from backup and restart
  }
}

When it happens

Trigger: MigrateToHierarchicalFS starting while the schema manager cannot answer Shards() for a class found in ReadOnlySchema — schema store read failure or class metadata inconsistency.

Common situations: Corrupted schema store files in the data directory; class present in schema but shard metadata missing after a crash; migration running before schema load completed.

Related errors

• could not load legacy schema: %w
• unknown datatype for aggregation type reference: ${dataType}
• updating schema
• class already exists
• class not found

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