github/github-mcp-server · error

field_filters: unknown field %q. Known fields: %s

Error message

field_filters: unknown field %q. Known fields: %s

What it means

resolveFieldFilters could not match a field_filters entry's name (case-insensitively) against any field defined on the repository's issues, and the error lists every known field name to guide correction. Fields come from the repository's issue field definitions fetched before resolution.

Source

Thrown at pkg/github/issues.go:3111

}

// resolveFieldFilters matches each raw filter against a known field definition and
// coerces the value into the right typed slot on IssueFieldValueFilter. Matching is
// case-insensitive on field name; option names are also matched case-insensitively for
// single-select fields.
func resolveFieldFilters(rawFilters []rawFieldFilter, fields []IssueField) ([]IssueFieldValueFilter, error) {
	byName := make(map[string]IssueField, len(fields))
	knownNames := make([]string, 0, len(fields))
	for _, f := range fields {
		byName[strings.ToLower(f.Name)] = f
		knownNames = append(knownNames, f.Name)
	}

	out := make([]IssueFieldValueFilter, 0, len(rawFilters))
	for _, rf := range rawFilters {
		field, ok := byName[strings.ToLower(rf.Name)]
		if !ok {
			return nil, fmt.Errorf("field_filters: unknown field %q. Known fields: %s", rf.Name, strings.Join(knownNames, ", "))
		}

		filter := IssueFieldValueFilter{FieldName: githubv4.String(field.Name)}
		switch field.DataType {
		case "SINGLE_SELECT":
			// Validate the option name against the field's options so we fail fast
			// with a useful error instead of an opaque GraphQL one.
			var matched string
			for _, o := range field.Options {
				if strings.EqualFold(o.Name, rf.Value) {
					matched = o.Name
					break
				}
			}
			if matched == "" {
				optionNames := make([]string, 0, len(field.Options))
				for _, o := range field.Options {
					optionNames = append(optionNames, o.Name)

View on GitHub (pinned to 0ea1f775a7)

Solutions

1. Pick the correct name from the 'Known fields' list printed in the error message
2. Re-list the repository's issue fields (the toolset's field-listing tool / GraphQL issueFields query) to see current names
3. Note that matching is case-insensitive, so only spelling — not casing — matters

Example fix

// before
{"field_filters":[{"field_name":"Sprint","value":"P1"}]}
// after
{"field_filters":[{"field_name":"Priority","value":"P1"}]}

func checkKnownField(name string, known []string) error {
	for _, k := range known {
		if strings.EqualFold(k, name) {
			return nil
		}
	}
	return fmt.Errorf("unknown field %q; known: %s", name, strings.Join(known, ", "))
}

func isKnownField(name string, known []string) bool {
	for _, k := range known {
		if strings.EqualFold(k, name) {
			return true
		}
	}
	return false
}

if err != nil && strings.Contains(err.Error(), "unknown field") {
    // Error already lists known fields; parse it and re-prompt with a valid name.
    known := extractKnownFields(err.Error())
    _ = known
}

When it happens

Trigger: Filtering on a field that does not exist in this repo, e.g. field_name "Sprint" when only Priority and Status exist; using a typo or a label name instead of a field name.

Common situations: Assuming another repository's project fields exist here; referencing built-in concepts (labels, milestones, assignees) that are not issue fields; custom fields renamed or deleted since the last run.

Related errors

• each field_filters entry must be an object
• field_filters must be an array
• field_filters entry: %s
• field_filters entry %q: %s
• field_filters: %q is not a valid option for %q. Valid option

AI-assisted analysis of github/github-mcp-server@0ea1f775a7 (2026-08-15). Data as JSON: /api/errors/78e19440142fe6c1. Report an issue: GitHub.