gastownhall/beads · error

failed to open %s: %w

Error message

failed to open %s: %w

What it means

loadMoleculesFromFile opens the molecules JSONL file; if os.Open fails, the OS error is wrapped with the path for context. This typically means the file is missing or unreadable.

Source

Thrown at internal/molecules/molecules.go:170

		SkipPrefixValidation: true, // Molecules use their own prefix
	}
	if err := l.store.CreateIssuesWithFullOptions(ctx, newMolecules, "molecules-loader", opts); err != nil {
		return 0, fmt.Errorf("batch create molecules: %w", err)
	}
	return len(newMolecules), nil
}

// loadMoleculesFromFile loads molecules from a JSONL file.
func loadMoleculesFromFile(path string) ([]*types.Issue, error) {
	// Check if file exists
	if _, err := os.Stat(path); os.IsNotExist(err) {
		return nil, nil
	}

	// #nosec G304 - path is constructed from known safe locations
	file, err := os.Open(path)
	if err != nil {
		return nil, fmt.Errorf("failed to open %s: %w", path, err)
	}
	defer file.Close()

	var molecules []*types.Issue
	scanner := bufio.NewScanner(file)
	lineNum := 0

	for scanner.Scan() {
		lineNum++
		line := scanner.Text()

		// Skip empty lines
		if strings.TrimSpace(line) == "" {
			continue
		}

		var issue types.Issue
		if err := json.Unmarshal([]byte(line), &issue); err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Check the path in the error exists: ls <path>; regenerate or restore molecules.jsonl if missing.
2. Fix the configured path/location for town- or project-level molecules files.
3. Fix filesystem permissions (chmod/chown) so the process user can read the file.

if _, err := os.Stat(path); err != nil {
    return fmt.Errorf("molecules file missing (%s): %w", path, err)
}

molecules, err := loadMoleculesFromFile(path)
if err != nil {
    if errors.Is(err, fs.ErrNotExist) {
        // generate or skip default molecules
        return nil
    }
    return err
}

When it happens

Trigger: os.Open(path) returns an error: file doesn't exist, wrong path configured for molecules.jsonl, or permission denied.

Common situations: Fresh clone where molecules.jsonl was never generated; typo'd path in configuration; running under a service account lacking read permission; town-level molecules path pointing at a non-existent directory.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• error reading %s: %w
• open batch file: %w
• open dependency file: %w
• read dependency file: %w
• no beads configuration found in %s

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/1d78d9337bcfb474. Report an issue: GitHub.