ipfs/kubo · error

datastore configuration of '%s' does not match what is on di

Error message

datastore configuration of '%s' does not match what is on disk '%s'

What it means

Repo open guard: the datastore spec derived from the config does not match the spec recorded on disk in the repo's _spec file. Kubo snapshots the spec at init time and refuses to open the repo against a differently-configured datastore, because on-disk layout (flatfs sharding etc.) must not silently change under an existing store.

Source

Thrown at repo/fsrepo/fsrepo.go:509

	} else if r.config.Datastore.Spec == nil {
		return fmt.Errorf("required Datastore.Spec entry missing from config file")
	}
	if r.config.Datastore.NoSync {
		log.Warn("NoSync is now deprecated in favor of datastore specific settings. If you want to disable fsync on flatfs set 'sync' to false. See https://github.com/ipfs/kubo/blob/master/docs/datastores.md#flatfs.")
	}

	dsc, err := AnyDatastoreConfig(r.config.Datastore.Spec)
	if err != nil {
		return err
	}
	spec := dsc.DiskSpec()

	oldSpec, err := r.readSpec()
	if err != nil {
		return err
	}
	if oldSpec != spec.String() {
		return fmt.Errorf("datastore configuration of '%s' does not match what is on disk '%s'",
			oldSpec, spec.String())
	}

	d, err := dsc.Create(r.path)
	if err != nil {
		return err
	}
	r.ds = d

	// Wrap it with metrics gathering
	prefix := "ipfs.fsrepo.datastore"
	r.ds = measure.New(prefix, r.ds)

	return nil
}

func (r *FSRepo) readSpec() (string, error) {
	fn, err := config.Path(r.path, specFn)

View on GitHub (pinned to 329838acdf)

Solutions

1. Revert the Datastore.Spec change in the config back to what the repo was created with
2. Or re-init a new repo with the desired spec and re-import the content
3. To intentionally migrate datastore types, follow a documented migration (export/import of the blockstore), not a config edit

When it happens

Trigger: Thrown at repo/fsrepo/fsrepo.go:509 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ipfs/kubo@329838acdf (2026-09-03). Data as JSON: /api/errors/fde93b07efa6a570. Report an issue: GitHub.