gastownhall/beads · error

no issues found in markdown file (expected ## Issue Title fo

Error message

no issues found in markdown file (expected ## Issue Title format)

What it means

The markdown parser extracts issues from `## Issue Title` headings. If the whole file is scanned and zero issues were collected, finalize returns this error: the file parsed fine but had no recognizable issue sections.

Source

Thrown at cmd/bd/markdown.go:245

	if line != "" {
		if s.currentIssue.Description != "" {
			s.currentIssue.Description += "\n"
		}
		s.currentIssue.Description += line
	}
}

// finalize completes parsing and returns the results
func (s *markdownParseState) finalize() ([]*IssueTemplate, error) {
	// Finalize last section and issue
	s.finalizeSection()
	if s.currentIssue != nil {
		s.issues = append(s.issues, s.currentIssue)
	}

	// Check if we found any issues
	if len(s.issues) == 0 {
		return nil, fmt.Errorf("no issues found in markdown file (expected ## Issue Title format)")
	}

	return s.issues, nil
}

// createMarkdownScanner creates a scanner with appropriate buffer size
func createMarkdownScanner(file *os.File) *bufio.Scanner {
	scanner := bufio.NewScanner(file)
	// Increase buffer size for large markdown files
	const maxScannerBuffer = 1024 * 1024 // 1MB
	buf := make([]byte, maxScannerBuffer)
	scanner.Buffer(buf, maxScannerBuffer)
	return scanner
}

func parseMarkdownFile(path string) ([]*IssueTemplate, error) {
	// Validate and clean the file path
	cleanPath, err := validateMarkdownPath(path)

View on GitHub (pinned to 71377f2769)

Solutions

1. Reformat each issue as a level-2 heading: `## Issue Title` followed by its body fields
2. Fix heading levels (convert `#`/`###` issue headings to `##`)
3. Move issue blocks out of code fences or blockquotes so the scanner sees the headings

Example fix

# before
# Fix login bug
# after
## Fix login bug

data, _ := os.ReadFile(path)
if !regexp.MustCompile(`(?m)^## .+`).Match(data) {
	return fmt.Errorf("%s has no '## Issue Title' headings", path)
}

When it happens

Trigger: parseMarkdownFile is given a syntactically valid .md file whose content uses headings other than `## Title` (e.g. `# Title`, `### Title`), or the file is empty/only prose, or issues are nested under a parent heading that shifts their level.

Common situations: Exported docs using H1 for issues; markdown generated by other tools with different conventions; an empty template file; issue blocks indented inside code fences so headings are not detected.

Related errors

• invalid dependency format %q for issue %q
• invalid dependency type %q for issue %q
• dolt version output is unparseable
• parsing batch input: %w
• line %d: %w

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