gastownhall/beads · error

cannot access file: %w

Error message

cannot access file: %w

What it means

After extension checks, validateMarkdownPath calls os.Stat on the cleaned path; any stat failure (most commonly the file not existing, but also permission errors on parent directories) is wrapped as "cannot access file: <os error>". This is a pre-flight existence check before opening the file.

Source

Thrown at cmd/bd/markdown.go:125

func validateMarkdownPath(path string) (string, error) {
	// Clean the path
	cleanPath := filepath.Clean(path)

	// Prevent directory traversal
	if strings.Contains(cleanPath, "..") {
		return "", fmt.Errorf("invalid file path: directory traversal not allowed")
	}

	// Ensure it's a markdown file
	ext := strings.ToLower(filepath.Ext(cleanPath))
	if ext != ".md" && ext != ".markdown" {
		return "", fmt.Errorf("invalid file type: only .md and .markdown files are supported")
	}

	// Check file exists and is not a directory
	info, err := os.Stat(cleanPath)
	if err != nil {
		return "", fmt.Errorf("cannot access file: %w", err)
	}
	if info.IsDir() {
		return "", fmt.Errorf("path is a directory, not a file")
	}

	return cleanPath, nil
}

// parseMarkdownFile parses a markdown file and extracts issue templates.
// Expected format:
//
//	## Issue Title
//	Description text...
//
//	### Priority
//	2
//
//	### Type

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the exact path exists: `ls -l <path>` (watch the working directory for relative paths)
2. Fix typos or use an absolute path
3. Check directory permissions (`chmod`/`chown`) so the bd process can traverse the path
4. If the file was generated by a prior step, confirm that step succeeded before importing

Example fix

// before
parseMarkdownFile("isues.md")
// after
parseMarkdownFile("./issues.md")   // correct spelling, verified with ls

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

When it happens

Trigger: parseMarkdownFile is called with a well-formed .md path that does not exist, sits in a directory the process cannot traverse, or has a symlink loop / too-long path causing os.Stat to error.

Common situations: Typo in filename; running from the wrong working directory; relative path resolved against an unexpected cwd in scripts; deleted temp files; permission-restricted directories.

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

• failed to read backup state: %w
• failed to write temp file: %w
• failed to sync temp file: %w
• failed to write issue %s: %w
• failed to create output file: %w

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