{"record":{"id":"97090d0877b48a12","repo":"weaviate/weaviate","slug":"unexpected-error-initializing-shard-q-of-index-q","errorCode":null,"errorMessage":"unexpected error initializing shard %q of index %q: %v","messagePattern":"unexpected error initializing shard %q of index %q: (.+?)","errorType":"panic","errorClass":null,"httpStatus":null,"severity":"error","filePath":"adapters/repos/db/shard_init.go","lineNumber":105,"sourceCode":"\t\tshutdownLock:  new(sync.RWMutex),\n\t\tshutCtx:       shutCtx,\n\t\tshutCtxCancel: shutCtxCancel,\n\n\t\tstatus:                          ShardStatus{Status: storagestate.StatusLoading},\n\t\tsearchableBlockmaxPropNamesLock: new(sync.Mutex),\n\t\treindexer:                       reindexer,\n\t\tusingBlockMaxWAND:               index.invertedIndexConfig.UsingBlockMaxWAND,\n\t\tbitmapBufPool:                   bitmapBufPool,\n\t\tlazySegmentLoadingEnabled:       lazyLoadSegments,\n\t\tregistration:                    registration,\n\t}\n\n\tindex.metrics.UpdateShardStatus(\"\", storagestate.StatusLoading.String())\n\n\tdefer func() {\n\t\tp := recover()\n\t\tif p != nil {\n\t\t\terr = fmt.Errorf(\"unexpected error initializing shard %q of index %q: %v\", shardName, index.ID(), p)\n\t\t\tindex.logger.WithError(err).WithFields(logrus.Fields{\n\t\t\t\t\"index\": index.ID(),\n\t\t\t\t\"shard\": shardName,\n\t\t\t}).Error(\"panic during shard initialization\")\n\t\t\tenterrors.PrintStack(index.logger)\n\t\t}\n\n\t\tif err != nil {\n\t\t\t// Initializing a shard should normally not fail. If it does, this could\n\t\t\t// mean that this setup requires further attention, e.g. to manually fix\n\t\t\t// a data corruption. This makes it a prime use case for sentry:\n\t\t\tentsentry.CaptureException(err)\n\t\t\t// spawn a new context as we cannot guarantee that the init context is\n\t\t\t// still valid, but we want to make sure that we have enough time to clean\n\t\t\t// up the partial init\n\t\t\tctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)\n\t\t\tdefer cancel()\n\t\t\ts.index.logger.WithFields(logrus.Fields{","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/weaviate/weaviate/blob/75aa4b6d11f8818305aafd4440b4e32794f7ca04/adapters/repos/db/shard_init.go#L87-L123","documentation":"NewShard recovers from any panic raised during shard initialization and converts it into this error (adapters/repos/db/shard_init.go:105). The deferred handler captures the recovered value p, builds the error with the shard and index IDs, logs it with a stack trace, captures it via Sentry, and runs cleanupPartialInit to remove partially created state. This prevents a panic in one shard from crashing the whole Weaviate process.","triggerScenarios":"Any panic inside the NewShard body after the deferred recover is installed — e.g. nil pointer dereference while constructing the Shard struct, panics in initCycleCallbacks, docIdLock setup, metric observation, or any downstream init that panics instead of returning an error.","commonSituations":"Hit by developers after a code change or version upgrade introduces a nil/map-access bug on the shard init path, when a class schema is unexpectedly shaped (nil config fields), or when corrupted on-disk state drives an initializer into a panic. Appears in logs as 'panic during shard initialization'.","solutions":["Read the logged stack trace (enterrors.PrintStack output) directly below this message to find the panicking line","Inspect the class schema/config for the affected shard for nil or malformed fields (e.g. vectorIndexConfig) that the init code dereferences","If tied to corrupted local state, stop Weaviate and restore the shard directory from a backup or re-create the shard","If reproducible after an upgrade, search the Weaviate issue tracker or file a bug with the stack trace — a panic here is always a library bug, never user error alone"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"// Go has no catch; the equivalent guard is checking the returned error, since\n// NewShard converts panics into errors:\nshard, err := db.NewShard(ctx, promMetrics, shardName, index, class, ...)\nif err != nil {\n\tindex.Logger.Errorf(\"shard %s failed to init (possible panic): %v\", shardName, err)\n\t// partial init was already cleaned up; do not use the nil shard\n\treturn err\n}","preventionTips":["Always treat the error return of NewShard as authoritative — panics are recovered and reported through it, never crash the caller","Ship the stack-trace log lines to your aggregator; the trace below this message identifies the library bug","Report reproducible panics to the Weaviate maintainers with the stack trace and class schema","Keep backups so a corrupted or odd-shaped shard can be restored instead of blocking startup"],"tags":["panic","shard-init","recovery","crash"],"backgroundTag":"panic-recovered-during-init","analyzedSha":"75aa4b6d11f8818305aafd4440b4e32794f7ca04","analyzedAt":"2026-09-04T14:58:20.392Z","contentChangedAt":"2026-09-04T14:58:20.392Z","schemaVersion":2},"datasetVersion":"2026-09-11T21:17:09.523Z"}