{"record":{"id":"76175d438204c7e7","repo":"gastownhall/beads","slug":"unknown-field-s-76175d","errorCode":null,"errorMessage":"unknown field: %s","messagePattern":"unknown field: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/query/evaluator.go","lineNumber":205,"sourceCode":"\tcase \"spec\", \"spec_id\":\n\t\treturn e.applySpecFilter(comp, filter)\n\tcase \"parent\":\n\t\treturn e.applyParentFilter(comp, filter)\n\tcase \"pinned\":\n\t\treturn e.applyBoolFilter(comp, filter, \"pinned\")\n\tcase \"ephemeral\":\n\t\treturn e.applyBoolFilter(comp, filter, \"ephemeral\")\n\tcase \"template\":\n\t\treturn e.applyBoolFilter(comp, filter, \"template\")\n\tcase \"mol_type\":\n\t\treturn e.applyMolTypeFilter(comp, filter)\n\tcase \"has_metadata_key\":\n\t\treturn e.applyHasMetadataKeyFilter(comp, filter)\n\tdefault:\n\t\tif strings.HasPrefix(comp.Field, \"metadata.\") {\n\t\t\treturn e.applyMetadataFilter(comp, filter)\n\t\t}\n\t\treturn fmt.Errorf(\"unknown field: %s\", comp.Field)\n\t}\n}\n\nfunc (e *Evaluator) applyStatusFilter(comp *ComparisonNode, filter *types.IssueFilter) error {\n\tif comp.Op != OpEquals && comp.Op != OpNotEquals {\n\t\treturn fmt.Errorf(\"status only supports = and != operators\")\n\t}\n\tstatus := types.Status(strings.ToLower(comp.Value))\n\tif !status.IsValid() {\n\t\treturn fmt.Errorf(\"invalid status: %s\", comp.Value)\n\t}\n\tif comp.Op == OpEquals {\n\t\tfilter.Status = &status\n\t} else {\n\t\tfilter.ExcludeStatus = append(filter.ExcludeStatus, status)\n\t}\n\treturn nil\n}","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/query/evaluator.go#L187-L223","documentation":"The beads query evaluator only accepts comparison fields from a fixed list (status, priority, type, assignee, owner, label(s), title, description, notes, created/updated/closed/started timestamps, id, spec, parent, pinned, ephemeral, template, mol_type, has_metadata_key, plus any field prefixed with \"metadata.\"). When applyComparison sees a field name outside that set and not a metadata. prefix, it rejects the whole query with this error. It is a query-authoring validation error, not a runtime/storage failure.","triggerScenarios":"Calling the query evaluator (bd list/filter queries) with a ComparisonNode whose Field is not one of the recognized names — e.g. typos like \"statues\", \"priorty\", \"labels.tags\", unquoted arbitrary identifiers like \"assignee_email\", or a foreign field name from another tool's query language (JQL/SOQL style).","commonSituations":"Typos in hand-written queries; copying query syntax from GitHub/Jira where fields like \"milestone\" or \"sprint\" exist but not in beads; schema drift after renaming a field in a script; assuming custom issue fields are queryable without the required \"metadata.\" prefix.","solutions":["Check the spelling of the field against the switch in internal/query/evaluator.go:158-200 (applyComparison) and correct it.","If filtering on a custom metadata entry, prefix the key with \"metadata.\" (e.g. metadata.team = ops) so it routes to applyMetadataFilter.","If the field genuinely should exist, add a case in applyComparison and a corresponding applyXxxFilter implementation — do not try to work around it client-side.","Run `bd schema` (or inspect types.IssueFilter) to see which fields are filterable before writing the query."],"exampleFix":"// before (typo'd / unknown field)\nfilter, err := query.Parse(\"statues = open\")\n// after\nfilter, err := query.Parse(\"status = open\")\n// custom metadata field:\n// before: \"team = ops\"\n// after:  \"metadata.team = ops\"","handlingStrategy":"validation","validationCode":"var validFields = map[string]bool{\"status\":true,\"priority\":true,\"type\":true,\"assignee\":true,\"owner\":true,\"label\":true,\"labels\":true,\"title\":true,\"description\":true,\"desc\":true,\"notes\":true,\"created\":true,\"created_at\":true,\"updated\":true,\"updated_at\":true,\"closed\":true,\"closed_at\":true,\"started\":true,\"started_at\":true,\"id\":true,\"spec\":true,\"spec_id\":true,\"parent\":true,\"pinned\":true,\"ephemeral\":true,\"template\":true,\"mol_type\":true,\"has_metadata_key\":true}\nfunc validQueryField(f string) bool { return validFields[f] || strings.HasPrefix(f, \"metadata.\") }","typeGuard":"func isComparisonNode(n query.Node) (*query.ComparisonNode, bool) { c, ok := n.(*query.ComparisonNode); return c, ok }","tryCatchPattern":"if err := evaluator.Apply(node, filter); err != nil {\n    var qe *query.Error\n    if errors.As(err, &qe) && strings.HasPrefix(qe.Msg, \"unknown field:\") {\n        return fmt.Errorf(\"query field %q is not filterable; see bd schema\", field)\n    }\n    return err\n}","preventionTips":["Keep a shared constant list of filterable fields and validate queries against it before evaluation.","Always prefix custom-field filters with \"metadata.\".","Run `bd schema` when unsure which fields exist.","Write unit tests for every query string shipped in scripts/config."],"tags":["query","validation","beads"],"backgroundTag":"unknown-query-field","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}