hasura/graphql-engine · error

the plugin name %q is not allowed, must match %q

Error message

the plugin name %q is not allowed, must match %q

What it means

ValidatePlugin rejects a plugin whose name does not satisfy the safe plugin name regexp. The library only accepts names matching a restricted pattern (defined by safePluginRegexp in cli/plugins/types.go) to avoid path traversal and unsafe characters when the name is later turned into binaries and symlinks. The error echoes the offending name and the exact regexp that must be matched.

Source

Thrown at cli/plugins/types.go:124

func (p *Plugin) ParseVersion() {
	v, err := semver.NewVersion(p.Version)
	if err != nil {
		p.ParsedVersion = semver.MustParse("0.0.0-dev")

		return
	}

	p.ParsedVersion = v
}

// ValidatePlugin checks for structural validity of the Plugin object with given
// name.
func (p Plugin) ValidatePlugin(name string) error {
	var op errors.Op = "plugins.Plugin.ValidatePlugin"
	if !IsSafePluginName(name) {
		return errors.E(
			op,
			fmt.Errorf(
				"the plugin name %q is not allowed, must match %q",
				name,
				safePluginRegexp.String(),
			),
		)
	}

	if p.Name != name {
		return errors.E(op, fmt.Errorf("plugin should be named %q, not %q", name, p.Name))
	}

	if p.ShortDescription == "" {
		return errors.E(op, "should have a short description")
	}

	if strings.ContainsAny(p.ShortDescription, "\r\n") {
		return errors.E(op, "should not have line breaks in short description")
	}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Rename the plugin to match safePluginRegexp.String() (shown verbatim in the error message) — typically lowercase letters, digits, hyphens/underscores, starting with a letter.
2. Check the file name / argument you pass to ReadPluginFromFile; it must equal the sanitized plugin name.
3. Sanitize user-supplied names before invoking the API.

Example fix

// before
err := p.ValidatePlugin("My Cool Plugin")

// after
err := p.ValidatePlugin("my-cool-plugin")

var safeName = regexp.MustCompile(`^[a-z][a-z0-9_-]*$`) // mirror safePluginRegexp

func assertSafeName(name string) error {
	if !safeName.MatchString(name) {
		return fmt.Errorf("name %q must match %s", name, safeName.String())
	}
	return nil
}

func isSafePluginName(name string) bool {
	return safeName.MatchString(name)
}

if err := p.ValidatePlugin(name); err != nil {
	var opErr errors.Error
	if errors.As(err, &opErr) && strings.Contains(err.Error(), "not allowed") {
		// sanitize or reject the name before retrying
	}
	return err
}

When it happens

Trigger: Calling ReadPluginFromFile (which calls Plugin.ValidatePlugin(name)) with a name containing characters outside safePluginRegexp — e.g. names with spaces, slashes, leading digits, or uppercase letters, depending on the pattern (typically ^[a-z][a-z0-9_-]*$ style).

Common situations: Manifest files named like 'My Plugin.json', names with dots or slashes, or names differing in case from what the registry expects. Also happens when the filename passed to ReadPluginFromFile derives from user input that was never sanitized.

Related errors

• plugin should be named %q, not %q
• platform (%+v) is badly constructed: %w
• `sha256` value %s is not valid, must match pattern %s
• `files` is invalid: %w
• plugin %q does not offer installation for this platform

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/234f4d667bc5095c. Report an issue: GitHub.