weaviate/weaviate · error

init index %q: %w

Error message

init index %q: %w

What it means

Wraps an os.MkdirAll failure while creating the index's on-disk directory during NewIndex. The index directory cannot be created, so the index (and its shards) cannot exist on this node — usually a filesystem/permission problem, not a schema problem.

Source

Thrown at adapters/repos/db/index.go:538

	if cfg.AsyncReplicationScheduler == nil && cfg.ReplicationFactor > 1 {
		return nil, fmt.Errorf("init index %q: async replication scheduler is required when ReplicationFactor > 1", cfg.ClassName.String())
	}
	if globalReplicationConfig == nil && cfg.ReplicationFactor > 1 {
		return nil, fmt.Errorf("init index %q: global replication config is required when ReplicationFactor > 1", cfg.ClassName.String())
	}
	index.asyncReplicationScheduler = cfg.AsyncReplicationScheduler

	index.closingCtx, index.closingCancel = context.WithCancel(context.Background())

	index.initCycleCallbacks()

	if err := index.checkSingleShardMigration(); err != nil {
		return nil, errors.Wrap(err, "migrating sharding state from previous version")
	}

	if err := os.MkdirAll(index.path(), os.ModePerm); err != nil {
		return nil, fmt.Errorf("init index %q: %w", index.ID(), err)
	}

	// Remove the snapshots root to clean up any bucket snapshots left behind
	// by operations that were interrupted (e.g. server crash). This runs once
	// at index creation time — not on every shard load — so it won't interfere
	// with a snapshot that may be in use after a tenant re-activation.
	if err := os.RemoveAll(index.snapshotsPath()); err != nil {
		logger.WithField("action", "remove_orphaned_snapshots").
			WithField("path", index.snapshotsPath()).
			Error(err)
	}

	if err := index.initAndStoreShards(ctx, class, promMetrics); err != nil {
		return nil, err
	}

	index.cycleCallbacks.compactionCycle.Start()
	index.cycleCallbacks.compactionAuxCycle.Start()

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Check filesystem permissions and ownership on the data directory (ls -ld; chown/chmod as needed)
2. Verify PERSISTENCE_DATA_PATH points to an existing writable volume
3. Check disk space (df -h) and free space or move the data directory
4. Ensure the path is not occupied by a regular file; remove/rename the offending file
5. If the volume is read-only, remount it read-write

if err := os.MkdirAll(dataPath, 0o755); err != nil {
  log.Fatalf("data dir not writable: %v", err)
}

idx, err := db.NewIndex(ctx, cfg)
if err != nil && strings.Contains(err.Error(), "init index") {
  // check PERSISTENCE_DATA_PATH mount, permissions, disk space before restart
}

When it happens

Trigger: os.MkdirAll(index.path()) fails: parent directory missing and uncreatable, insufficient permissions, read-only filesystem, disk full, or the path exists as a regular file, or persistent-ancestors (PERSISTENCE_DATA_PATH) points somewhere invalid.

Common situations: Docker container with read-only or wrongly-mounted data volume; wrong PERSISTENCE_DATA_PATH env var; running as non-root user without write access; disk exhausted after a large import; leftover file where the index dir should be.

Related errors

• remove orphaned changelog %q: %w
• failed to rename old compressed vector bucket for target vec
• export requires a filesystem that supports hard links; the d
• init shard %s of index %s: %w
• recovery rename ingest->main for %q: %w

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