What causes "path is a directory, not a file" in gastownhall/beads?

Pass an individual .md file path, not a directory

path is a directory, not a file

Error message

path is a directory, not a file

What it means

os.Stat succeeds but reports the path is a directory; the markdown parser requires a regular file, so validateMarkdownPath rejects directories explicitly. This prevents confusing downstream scanner failures when a directory is handed to the import.

Source

Thrown at cmd/bd/markdown.go:128

	// 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
//	feature
//
//	### Description

View on GitHub (pinned to 71377f2769)

Solutions

Pass an individual .md file path, not a directory
Loop over the directory's .md files and import each one
Rename the directory if it misleadingly has a markdown extension

Example fix

// before
parseMarkdownFile("docs/issues.md/")
// after
parseMarkdownFile("docs/issues.md/backend.md")   // a file inside the directory

Defensive patterns

Strategy: validation

Validate before calling

fi, err := os.Stat(path)
if err == nil && fi.IsDir() {
	return fmt.Errorf("%s is a directory; pass a file", path)
}

Prevention

Check the target is a file, not a directory, before import
Beware directories named with .md suffixes
Iterate directory contents yourself instead of passing the directory

When it happens

Trigger: Passing a directory path ending in `.md`/`.markdown` (e.g. `notes/` inside a directory literally named `something.md`) or simply a directory to the markdown import API.

Common situations: Pointing import at a folder of markdown files instead of a single file; a directory named `docs.md`; globbing that expanded to a directory.

Related errors

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