ipfs/kubo · error

ipfs not initialized, please run 'ipfs init'

Error message

ipfs not initialized, please run 'ipfs init'

What it means

ErrNotInitialized is the sentinel error returned by serialize.ReadConfigFile (and ReadUserResourceOverrides/openUserResourceOverrides) when the target config file does not exist (os.IsNotExist). It signals that the IPFS repo has not been initialized. Callers such as fsrepo detect it via errors.Is and either prompt initialization or treat missing resource-override files as optional.

Source

Thrown at config/serialize/serialize.go:18

package fsrepo

import (
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"path/filepath"

	"github.com/ipfs/kubo/config"

	"github.com/facebookgo/atomicfile"
)

// ErrNotInitialized is returned when we fail to read the config because the
// repo doesn't exist.
var ErrNotInitialized = errors.New("ipfs not initialized, please run 'ipfs init'")

// ReadConfigFile reads the config from `filename` into `cfg`.
func ReadConfigFile(filename string, cfg any) error {
	f, err := os.Open(filename)
	if err != nil {
		if os.IsNotExist(err) {
			err = ErrNotInitialized
		}
		return err
	}
	defer f.Close()
	if err := json.NewDecoder(f).Decode(cfg); err != nil {
		return fmt.Errorf("failure to decode config: %w", err)
	}
	return nil
}

// WriteConfigFile writes the config from `cfg` into `filename`.

View on GitHub (pinned to 329838acdf)

Solutions

1. Run `ipfs init` to create the repo and its config file.
2. Verify IPFS_PATH points at the directory containing the existing repo (default ~/.ipfs).
3. If the repo was moved, restore the config file or re-init and copy settings over.

Example fix

// before: running commands against uninitialized repo
export IPFS_PATH=/tmp/nonexistent
ipfs daemon // fails with ErrNotInitialized
// after
export IPFS_PATH=/tmp/mynode
ipfs init
ipfs daemon

if _, err := os.Stat(filepath.Join(ipfsPath, "config")); os.IsNotExist(err) {
    return fmt.Errorf("repo at %s not initialized; run 'ipfs init'", ipfsPath)
}

func isNotInitialized(err error) bool { return errors.Is(err, serialize.ErrNotInitialized) }

if err := doThing(); err != nil {
    if errors.Is(err, serialize.ErrNotInitialized) {
        // run 'ipfs init' or surface an init prompt
        return initRepo()
    }
    return err
}

When it happens

Trigger: Running any command that needs the repo config (e.g. `ipfs config show`, daemon start, fsrepo.Open/Load) when IPFS_PATH/$IPFS_PATH/config does not exist; also reading libp2p-resource-limit-overrides.json when that file is absent (fsrepo.go maps it back to nil).

Common situations: Running `ipfs` before ever running `ipfs init`, pointing IPFS_PATH at a wrong/empty directory, running the daemon in a fresh container without an init step, or CI forgetting the init step.

Related errors

• reading repo config: %w
• cannot access config, repo not open
• could not read config: %w
• mountFuse: GetConfig() failed: %s
• %s path cannot be empty

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