What causes "failed to check init flag file: %w" in charmbracelet/crush?

Check permissions on the data directory and the flag file path (ls -la).

failed to check init flag file: %w

Error message

failed to check init flag file: %w

What it means

Returned by ProjectNeedsInitialization when os.Stat on the init flag file fails with an error other than NotExist (e.g. permission denied, path is invalid, or an I/O error). The function only tolerates 'file missing' or 'file exists'; any other stat failure is wrapped here.

Source

Thrown at internal/config/init.go:43

	}
	return store, nil
}

func ProjectNeedsInitialization(store *ConfigStore) (bool, error) {
	if store == nil {
		return false, fmt.Errorf("config not loaded")
	}

	cfg := store.Config()
	flagFilePath := filepath.Join(cfg.Options.DataDirectory, InitFlagFilename)

	_, err := os.Stat(flagFilePath)
	if err == nil {
		return false, nil
	}

	if !os.IsNotExist(err) {
		return false, fmt.Errorf("failed to check init flag file: %w", err)
	}

	someContextFileExists, err := contextPathsExist(store.WorkingDir())
	if err != nil {
		return false, fmt.Errorf("failed to check for context files: %w", err)
	}
	if someContextFileExists {
		return false, nil
	}

	// If the working directory has no non-ignored files, skip initialization step
	empty, err := dirHasNoVisibleFiles(store.WorkingDir())
	if err != nil {
		return false, fmt.Errorf("failed to check if directory is empty: %w", err)
	}
	if empty {
		return false, nil
	}

View on GitHub (pinned to 7944b8e522)

Solutions

Check permissions on the data directory and the flag file path (ls -la).
Verify cfg.Options.DataDirectory points to a valid, accessible directory.
Fix the mount/volume state if the data directory is on an unmounted or read-only filesystem.
Ensure the process user owns or can access the data directory.

Example fix

// before
if err := os.Chmod(dataDir, 0o000); err != nil { ... }
// after: keep data dir writable by the running user
if err := os.Chmod(dataDir, 0o755); err != nil {
	return fmt.Errorf("fix data dir permissions: %w", err)
}

Defensive patterns

Strategy: validation

Validate before calling

fi, err := os.Stat(dataDir)
if err != nil || !fi.IsDir() {
	return fmt.Errorf("data dir invalid: %w", err)
}
if err := syscall.Access(dataDir, unix.W_OK); err != nil {
	return fmt.Errorf("data dir not writable: %w", err)
}

Type guard

func isPermOrIOError(err error) bool {
	return err != nil && !os.IsNotExist(err)
}

Try / catch

if err != nil && strings.Contains(err.Error(), "failed to check init flag file") {
	// verify data dir permissions/mount, then retry
}

Prevention

Keep the data directory owned by the running user with 0o755.
Verify the volume holding the data dir is mounted and writable at startup.
Do not point DataDirectory at removable or network paths.
Avoid running some commands under sudo and others as the normal user.

When it happens

Trigger: Calling ProjectNeedsInitialization when the init flag file path inside cfg.Options.DataDirectory is unreadable: permission errors, DataDirectory pointing somewhere invalid, or filesystem I/O errors (e.g. broken mount).

Common situations: Data directory on a read-only or unmounted volume; restrictive file permissions after running as different users; DataDirectory misconfigured in crushrc options.

Related errors

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/59f2b1082eb65918. Report an issue: GitHub.