Error finding your home directory Can't load config files: %

Error message

Error finding your home directory
Can't load config files: %s

What it means

Returned by config.InitConfigDir when neither MICRO_CONFIG_HOME nor XDG_CONFIG_HOME is set and the homedir library cannot determine the user's home directory (homedir.Dir() error). Without a home, micro cannot derive ~/.config/micro, so it reports it cannot load config files. The wrapped underlying error explains the specific failure.

Source

Thrown at internal/config/config.go:26

	homedir "github.com/mitchellh/go-homedir"
)

var ConfigDir string

// InitConfigDir finds the configuration directory for micro according to the XDG spec.
// If no directory is found, it creates one.
func InitConfigDir(flagConfigDir string) error {
	var e error

	microHome := os.Getenv("MICRO_CONFIG_HOME")
	if microHome == "" {
		// The user has not set $MICRO_CONFIG_HOME so we'll try $XDG_CONFIG_HOME
		xdgHome := os.Getenv("XDG_CONFIG_HOME")
		if xdgHome == "" {
			// The user has not set $XDG_CONFIG_HOME so we should act like it was set to ~/.config
			home, err := homedir.Dir()
			if err != nil {
				return errors.New("Error finding your home directory\nCan't load config files: " + err.Error())
			}
			xdgHome = filepath.Join(home, ".config")
		}

		microHome = filepath.Join(xdgHome, "micro")
	}
	ConfigDir = microHome

	if len(flagConfigDir) > 0 {
		if _, err := os.Stat(flagConfigDir); os.IsNotExist(err) {
			e = errors.New("Error: " + flagConfigDir + " does not exist. Defaulting to " + ConfigDir + ".")
		} else {
			ConfigDir = flagConfigDir
			return nil
		}
	}

	// Create micro config home directory if it does not exist

View on GitHub (pinned to 1c8b82b32e)

Solutions

Set HOME for the invoking user: export HOME=/home/$USER (or USERPROFILE on Windows).
Or set XDG_CONFIG_HOME to any absolute path: export XDG_CONFIG_HOME=/etc/xdg (micro then uses $XDG_CONFIG_HOME/micro).
Or set MICRO_CONFIG_HOME directly: export MICRO_CONFIG_HOME=/path/with/config — this bypasses home lookup entirely.
For containers: add `ENV HOME=/root` or a valid USER so passwd lookup works.

Example fix

# before:
docker run --rm -it myimage micro   # no HOME set -> error

# after:
docker run --rm -it -e HOME=/root myimage micro

Defensive patterns

Strategy: validation

Validate before calling

func ensureConfigEnv() error {
    if os.Getenv("MICRO_CONFIG_HOME") != "" || os.Getenv("XDG_CONFIG_HOME") != "" {
        return nil
    }
    if os.Getenv("HOME") == "" { // windows: USERPROFILE
        return errors.New("no HOME set; micro cannot find its config dir")
    }
    return nil
}
// run before invoking micro or config.InitConfigDir

Try / catch

if err := config.InitConfigDir(""); err != nil {
    if strings.HasPrefix(err.Error(), "Error finding your home directory") {
        // set a concrete config dir and retry: config.InitConfigDir("/tmp/micro-config")
    }
}

Prevention

In containers/cron/systemd units, always set HOME (or USERPROFILE) or XDG_CONFIG_HOME for the run.
For deterministic embeds, pass -config-dir or MICRO_CONFIG_HOME explicitly so home lookup is skipped.
Fail fast in launch scripts: [ -n "$HOME" ] || export HOME=/tmp before exec micro.

When it happens

Trigger: Running micro in an environment with a stripped env: no HOME on Unix (go-homedir falls back to `getent passwd`/shells; in minimal containers that can also fail), no USERPROFILE on Windows, or a container/cron/systemd unit that clears environment variables. Fires at internal/config/config.go:26.

Common situations: Docker containers run without HOME, CI jobs, `env -i micro`, cron entries, or launching micro from a service manager unit without a User= directive / environment block.

Related errors

AI-assisted analysis of micro-editor/micro@1c8b82b32e (2026-08-15). Data as JSON: /api/errors/fd068f99c82a24fd. Report an issue: GitHub.