weaviate/weaviate · critical

parsing class %q: %w

Error message

parsing class %q: %w

What it means

During schema restore, every class in the decoded snapshot is run through parser.ParseClass to validate and normalize it. If parsing fails for any class, restore aborts with this wrapped error naming the offending class. The code comment notes this 'should not fail' in normal operation, so a failure means the stored schema is corrupted or contains classes that no longer satisfy the parser's validation rules.

Source

Thrown at cluster/schema/schema.go:787

}

func (s *schema) RestoreLegacy(data []byte, parser Parser) error {
	snap := snapshot{}
	if err := json.Unmarshal(data, &snap); err != nil {
		return fmt.Errorf("restore snapshot: decode json: %w", err)
	}

	if snap.Classes == nil {
		snap.Classes = make(map[string]*metaClass)
	}

	return s.restore(snap.Classes, parser)
}

func (s *schema) restore(classes map[string]*metaClass, parser Parser) error {
	for _, cls := range classes {
		if err := parser.ParseClass(&cls.Class); err != nil { // should not fail
			return fmt.Errorf("parsing class %q: %w", cls.Class.Class, err) // schema might be corrupted
		}
		cls.Sharding.SetLocalName(s.nodeID)
	}
	s.replaceClasses(classes)
	return nil
}

func (s *schema) RestoreAlias(data []byte) error {
	s.mu.Lock()
	defer s.mu.Unlock()

	s.aliases = make(map[string]string)
	if err := json.Unmarshal(data, &s.aliases); err != nil {
		return fmt.Errorf("restore alias: parse json: %w", err)
	}
	return nil
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Inspect the named class in the snapshot file and fix the invalid field (missing class name, bad vectorizer/module config, malformed property definitions).
2. Restore a snapshot from the same or compatible Weaviate version; upgrade-incompatible snapshots must go through export/import of the schema instead of file-level restore.
3. Remove the corrupt class entry from the snapshot if it is no longer needed, then retry restore.
4. Rebuild the node's persistence directory from a verified backup or re-bootstrap the node into the cluster so Raft replays a good snapshot.

Example fix

// before: restoring a snapshot with an invalid class config
err := schema.Restore(data, parser)
// -> "parsing class \"Article\": ..."

// after: validate each class up front and repair before restore
var snap snapshot
json.Unmarshal(data, &snap)
for name, cls := range snap.Classes {
    if err := parser.ParseClass(&cls.Class); err != nil {
        log.Fatalf("class %q in snapshot is invalid, repair or remove it: %v", name, err)
    }
}
err := schema.Restore(data, parser)

var snap snapshot
if err := json.Unmarshal(data, &snap); err != nil {
    return err
}
for name, cls := range snap.Classes {
    if err := parser.ParseClass(&cls.Class); err != nil {
        return fmt.Errorf("class %q in snapshot is invalid: %w", name, err)
    }
}

if err := schema.Restore(data, parser); err != nil {
    // err names the offending class
    log.Printf("schema restore failed, inspect the named class: %v", err)
}

When it happens

Trigger: Calling Restore or RestoreLegacy where any metaClass in the snapshot fails ParseClass — e.g. a class missing required fields, an invalid vectorizer/module configuration, or an unparsable inverted-index/sharding config in the snapshot.

Common situations: Restoring a snapshot from an older Weaviate version whose class definitions fail the current parser's validation; hand-edited schema snapshots; partially written snapshot data after a crash; module configs referencing modules not configured on the new node.

Related errors

• nil class or empty class name: %w
• empty property or empty class name: %w
• empty classes names: %w
• unknown datatype for aggregation type reference: ${dataType}
• IndexPropertyLength cannot be changed when updating a schema

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