charmbracelet/crush · error

failed to check for context files: %w

Error message

failed to check for context files: %w

What it means

Returned by ProjectNeedsInitialization when contextPathsExist fails while checking whether any context file (AGENTS.md, CRUSH.md, CLAUDE.md, GEMINI.md, etc.) exists in the working directory. Wrapped from an underlying filesystem error.

Source

Thrown at internal/config/init.go:48

	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
	}

	return true, nil
}

func contextPathsExist(dir string) (bool, error) {

View on GitHub (pinned to 7944b8e522)

Solutions

1. Verify the process has read (and traverse) permission on store.WorkingDir().
2. Confirm the working directory still exists and is accessible.
3. Check sandbox/SELinux/AppArmor policies that may block directory traversal.
4. Retry if the failure is a transient remote-filesystem error.

Example fix

// before
os.Chdir(deletedDir)
needsInit, err := config.ProjectNeedsInitialization(store)
// after
if _, err := os.Stat(workDir); err != nil {
	return fmt.Errorf("working dir unavailable: %w", err)
}
needsInit, err := config.ProjectNeedsInitialization(store)

if fi, err := os.Stat(workDir); err != nil || !fi.IsDir() {
	return fmt.Errorf("working dir unreadable: %w", err)
}

func isAccessError(err error) bool {
	return errors.Is(err, fs.ErrPermission) || errors.Is(err, fs.ErrNotExist)
}

if err != nil && strings.Contains(err.Error(), "failed to check for context files") {
	// check dir permissions / sandbox, then retry
}

When it happens

Trigger: Calling ProjectNeedsInitialization in a working directory where the context-file existence check hits a filesystem error — permission denied on the directory, the directory was deleted mid-run, or an I/O failure while globbing/statting candidate paths.

Common situations: Running in a directory the process cannot read; working directory removed while the app runs; NFS/remote filesystem hiccups; over-restrictive umask or sandboxing blocking directory reads.

Related errors

• failed to create parent directories: %w
• failed to create output file: %w
• failed to access file: %w
• failed to create parent directories: %w
• session ID is required for accessing directories outside wor

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