gastownhall/beads · error

failed to create output file: %w

Error message

failed to create output file: %w

What it means

exportDiagnostics wraps any error returned by os.Create when it cannot open the requested output file for writing. The doctor command uses this to report that the JSON diagnostics file could not be created. The wrapped error (%w) carries the OS-level reason (permissions, path issues, etc.).

Source

Thrown at cmd/bd/doctor.go:1111

		Detail:   dc.Detail,
		Fix:      dc.Fix,
		Category: dc.Category,
	}
}

// convertWithCategory converts a doctor check and sets its category
func convertWithCategory(dc doctor.DoctorCheck, category string) doctorCheck {
	check := convertDoctorCheck(dc)
	check.Category = category
	return check
}

// exportDiagnostics writes the doctor result to a JSON file
func exportDiagnostics(result doctorResult, outputPath string) error {
	// #nosec G304 - outputPath is a user-provided flag value for file generation
	f, err := os.Create(outputPath)
	if err != nil {
		return fmt.Errorf("failed to create output file: %w", err)
	}
	defer f.Close()

	encoder := json.NewEncoder(f)
	encoder.SetIndent("", "  ")
	if err := encoder.Encode(result); err != nil {
		return fmt.Errorf("failed to write JSON: %w", err)
	}

	return nil
}

func printDiagnostics(result doctorResult) {
	// Pre-calculate counts and collect issues grouped by category
	checksByCategory := make(map[string][]doctorCheck)
	issuesByCategory := make(map[string][]doctorCheck)
	var passCount, warnCount, failCount int
	hasIssues := false

View on GitHub (pinned to 71377f2769)

Solutions

1. Create the parent directory first (mkdir -p <dir>) or correct the output path
2. Check directory write permissions (ls -ld <dir>) and fix with chmod/chown or pick another directory
3. Ensure the path is a file, not an existing directory
4. Run from a location/filesystem that is writable (avoid read-only mounts, full disks via df -h)

Example fix

// before
bd doctor --output /nonexistent/dir/diag.json
// after
mkdir -p ./diagnostics
bd doctor --output ./diagnostics/diag.json

import "os"
func ensureWritable(path string) error {
	dir := filepath.Dir(path)
	if st, err := os.Stat(dir); err != nil {
		return fmt.Errorf("output dir missing: %w", err)
	} else if !st.IsDir() {
		return fmt.Errorf("%s is not a directory", dir)
	}
	f, err := os.OpenFile(path, os.O_CREATE|os.O_WRONLY, 0o644)
	if err != nil { return err }
	return f.Close()
}

if err := exportDiagnostics(result, outPath); err != nil {
	var pe *fs.PathError
	if errors.As(err, &pe) {
		log.Fatalf("cannot write %s: %v (check dir exists and is writable)", pe.Path, pe.Err)
	}
	return err
}

When it happens

Trigger: Calling `bd doctor` with an --output path whose parent directory does not exist, is not writable, or where the path is a directory; os.Create then fails and exportDiagnostics wraps it at cmd/bd/doctor.go:1111.

Common situations: Typo'd output path (e.g. -o /nonexistent/dir/out.json), read-only filesystem, no write permission in the target directory, path pointing to an existing directory, or running without sufficient privileges in restricted locations.

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 write JSON: %w

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