matryer/xbar · error

not an xbar:// url

Error message

not an xbar:// url

What it means

parseIncomingURL only accepts URLs whose scheme is 'xbar' (or whose host is 'app.xbarapp.com'). Any other input — https://, plain text, empty string, malformed URLs — fails this scheme/host check and is rejected so the app never dispatches an action from a foreign link. It is thrown early, before any action or params are extracted.

Source

Thrown at app/incoming_urls.go:25

	"github.com/pkg/errors"
)

type incomingURL struct {
	// Action is the action to take.
	Action string
	// Params are the parameters for the action.
	Params url.Values
}

// parseIncomingURL parses an incoming xbar:// URL.
func parseIncomingURL(urlStr string) (incomingURL, error) {
	var inURL incomingURL
	u, err := url.Parse(urlStr)
	if err != nil {
		return inURL, err
	}
	if u.Scheme != "xbar" && u.Host != "app.xbarapp.com" {
		return inURL, errors.New("not an xbar:// url")
	}
	inURL.Action = strings.Trim(u.Path, "/")
	inURL.Params = u.Query()
	switch inURL.Action {
	case "openPlugin":
	case "refreshPlugin":
	case "refreshAllPlugins":
	default: // not ok
		return inURL, errors.Errorf("unsupported action %q", inURL.Action)
	}
	return inURL, nil
}

View on GitHub (pinned to d624239058)

Solutions

1. Ensure the URL string starts with the xbar:// scheme, e.g. xbar://openPlugin?path=...
2. If using an https deep link, make sure the host is exactly app.xbarapp.com and the path is /<action>
3. URL-decode the input if it arrived percent-encoded, then re-parse
4. Fix the OS/browser handler so xbar:// links reach the app unchanged instead of being rewritten to https

Example fix

// before
parseIncomingURL("https://example.com/refreshAllPlugins")
// after
parseIncomingURL("xbar://refreshAllPlugins")

func isXbarURL(raw string) bool {
	u, err := url.Parse(raw)
	if err != nil {
		return false
	}
	return u.Scheme == "xbar" || u.Host == "app.xbarapp.com"
}

func isXbarURL(u *url.URL) bool {
	return u != nil && (u.Scheme == "xbar" || u.Host == "app.xbarapp.com")
}

inURL, err := parseIncomingURL(raw)
if err != nil {
	if err.Error() == "not an xbar:// url" {
		// reject or show a friendly 'unsupported link' message
		return
	}
	return err
}

When it happens

Trigger: Calling parseIncomingURL (directly or via handleIncomingURL) with a string that is not an xbar:// URL and not an app.xbarapp.com URL, e.g. "https://xbarapp.com/openPlugin", "", or "foo://bar". Note the check uses && so a URL like "mailto:app.xbarapp.com" (wrong scheme AND right host absent) also fails.

Common situations: Deep links pasted from a browser with the scheme mangled or URL-encoded; users clicking an https link instead of the xbar:// link from docs; tests passing arbitrary URLs; OS registering the xbar:// handler to a different app so a normalized https URL is forwarded.

Related errors

• unsupported action %q
• malformed xbar.var format
• malformed xbar.var format (missing select options)
• malformed xbar.var format (empty select options)
• disabled

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