weaviate/weaviate · error

unexpected error initializing shard %q of index %q: %v

Error message

unexpected error initializing shard %q of index %q: %v

What it means

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.

Source

Thrown at adapters/repos/db/shard_init.go:105

		shutdownLock:  new(sync.RWMutex),
		shutCtx:       shutCtx,
		shutCtxCancel: shutCtxCancel,

		status:                          ShardStatus{Status: storagestate.StatusLoading},
		searchableBlockmaxPropNamesLock: new(sync.Mutex),
		reindexer:                       reindexer,
		usingBlockMaxWAND:               index.invertedIndexConfig.UsingBlockMaxWAND,
		bitmapBufPool:                   bitmapBufPool,
		lazySegmentLoadingEnabled:       lazyLoadSegments,
		registration:                    registration,
	}

	index.metrics.UpdateShardStatus("", storagestate.StatusLoading.String())

	defer func() {
		p := recover()
		if p != nil {
			err = fmt.Errorf("unexpected error initializing shard %q of index %q: %v", shardName, index.ID(), p)
			index.logger.WithError(err).WithFields(logrus.Fields{
				"index": index.ID(),
				"shard": shardName,
			}).Error("panic during shard initialization")
			enterrors.PrintStack(index.logger)
		}

		if err != nil {
			// Initializing a shard should normally not fail. If it does, this could
			// mean that this setup requires further attention, e.g. to manually fix
			// a data corruption. This makes it a prime use case for sentry:
			entsentry.CaptureException(err)
			// spawn a new context as we cannot guarantee that the init context is
			// still valid, but we want to make sure that we have enough time to clean
			// up the partial init
			ctx, cancel := context.WithTimeout(context.Background(), 120*time.Second)
			defer cancel()
			s.index.logger.WithFields(logrus.Fields{

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Read the logged stack trace (enterrors.PrintStack output) directly below this message to find the panicking line
2. Inspect the class schema/config for the affected shard for nil or malformed fields (e.g. vectorIndexConfig) that the init code dereferences
3. If tied to corrupted local state, stop Weaviate and restore the shard directory from a backup or re-create the shard
4. 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

// Go has no catch; the equivalent guard is checking the returned error, since
// NewShard converts panics into errors:
shard, err := db.NewShard(ctx, promMetrics, shardName, index, class, ...)
if err != nil {
	index.Logger.Errorf("shard %s failed to init (possible panic): %v", shardName, err)
	// partial init was already cleaned up; do not use the nil shard
	return err
}

When it happens

Trigger: 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.

Common situations: 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'.

Related errors

• panic in async replication batch: %v
• an unexpected error occurred: %s
• panic occurred: %v
• previous shutdown attempt failed mid-teardown
• backup did not run to completion

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