What causes "missing xbar.image" in matryer/xbar?

Add an https://.../screenshot.png comment block pointing to a public image

missing xbar.image

Error message

missing xbar.image

What it means

Plugin.Validate requires the plugin to have a usable image, checked via HasImage(p.ImageURL). The image is the plugin's screenshot/preview in the xbar directory, so a plugin without one fails validation.

Source

Thrown at pkg/metadata/plugin_metadata.go:77

	LastUpdated time.Time `json:"lastUpdated"`
	// Vars are the configurable values for this Plugin.
	Vars []PluginVar `json:"vars"`

	// ProcessingNotes is a list of errors/warnings/notes that are set during
	// the processing of this plugin.
	ProcessingNotes []string `json:"processingNotes"`
}

// Validate checks the plugin data.
func (p Plugin) Validate() error {
	if p.Title == "" {
		return errors.New("missing xbar.title")
	}
	if p.Desc == "" {
		return errors.New("missing xbar.desc")
	}
	if !HasImage(p.ImageURL) {
		return errors.New("missing xbar.image")
	}
	if len(p.Authors) == 0 {
		return errors.New("missing xbar.author")
	}
	return nil // ok
}

// NiceDesc gets a nice description.
func (p Plugin) NiceDesc() string {
	if p.Desc == "" {
		return p.Title
	}
	return truncate(p.Desc, 75)
}

// File is a single file.
type File struct {
	// Path is the path of the File.

View on GitHub (pinned to d624239058)

Solutions

Add an <xbar.image>https://.../screenshot.png</xbar.image> comment block pointing to a public image
Set the ImageURL field (a value HasImage accepts) before Validate
Host the screenshot somewhere publicly reachable (e.g. GitHub) and re-parse

Example fix

// before (plugin script metadata)
// <xbar.image></xbar.image>
// after
// <xbar.image>https://raw.githubusercontent.com/user/repo/main/screenshot.png</xbar.image>

Defensive patterns

Strategy: validation

Validate before calling

func hasImageURL(p metadata.Plugin) bool {
	return strings.TrimSpace(p.ImageURL) != "" &&
		(p.ImageURL[:4] == "http" || p.ImageURL[:3] == "data")
}

Type guard

func hasValidImage(p metadata.Plugin) bool {
	return p.ImageURL != "" // mirrors metadata.HasImage
}

Try / catch

if err := plugin.Validate(); err != nil {
	if err.Error() == "missing xbar.image" {
		return fmt.Errorf("plugin %s: add an <xbar.image> comment with a public screenshot URL: %w", path, err)
	}
	return err
}

Prevention

Commit a screenshot to the plugin repo and reference it via a raw.githubusercontent URL
Verify the image URL is publicly reachable (no auth-required hosts)
Never leave the <xbar.image> value empty
Check HasImage in CI before submitting to the directory

When it happens

Trigger: Plugin.Validate called on a Plugin whose ImageURL is empty or otherwise fails HasImage — the script has no <xbar.image>...</xbar.image> comment or the URL inside is blank/invalid.

Common situations: Author skipped adding a screenshot; image URL points to a private or deleted asset so it was treated as missing; image comment removed by a linter; programmatically built Plugin with ImageURL unset.

Related errors

AI-assisted analysis of matryer/xbar@d624239058 (2026-09-02). Data as JSON: /api/errors/ee432d5c83b6ad82. Report an issue: GitHub.