{"record":{"id":"708fd060cb3a9e15","repo":"cayleygraph/cayley","slug":"must-execute-a-iteratorstep-or-pathstep","errorCode":null,"errorMessage":"must execute a IteratorStep or PathStep","messagePattern":"must execute a IteratorStep or PathStep","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"query/linkedql/linkedql.go","lineNumber":69,"sourceCode":"\t\treturn nil, err\n\t}\n\tns := voc.Namespaces{}\n\tstep, ok := item.(Step)\n\tif !ok {\n\t\treturn nil, errors.New(\"must execute a Step\")\n\t}\n\treturn BuildIterator(step, s.qs, &ns)\n}\n\n// BuildIterator for given Step returns a query.Iterator\nfunc BuildIterator(step Step, qs graph.QuadStore, ns *voc.Namespaces) (query.Iterator, error) {\n\tswitch s := step.(type) {\n\tcase IteratorStep:\n\t\treturn s.BuildIterator(qs, ns)\n\tcase PathStep:\n\t\treturn NewValueIteratorFromPathStep(s, qs, ns)\n\t}\n\treturn nil, errors.New(\"must execute a IteratorStep or PathStep\")\n}\n","sourceCodeStart":51,"sourceCodeEnd":71,"githubUrl":"https://github.com/cayleygraph/cayley/blob/81dcd7d73e45136bc0d01802a8ba4685d8a533eb/query/linkedql/linkedql.go#L51-L71","documentation":"BuildIterator in the linkedql package converts a query step into an iterator, but only steps implementing IteratorStep or PathStep are executable. If the passed step implements neither interface, Cayley returns this error instead of guessing how to build an iterator. It indicates the query step type is not executable as given.","triggerScenarios":"Calling linkedql.BuildIterator (directly or via query.Execute) with a step value that implements neither IteratorStep nor PathStep, e.g. a custom or third-party step, or a step constructed/registered incorrectly.","commonSituations":"Registering a custom query step without implementing BuildIterator; passing a placeholder or wrapper step; type registration mismatch after decoding a query from JSON so the step unmarshals into a generic type.","solutions":["Check that the step's concrete type implements linkedql.IteratorStep (BuildIterator method) or linkedql.PathStep; implement the missing method.","Verify the step was constructed with the correct linkedql step type, not a generic or partial struct.","Update to a version where the step type is executable, or replace the step with a supported equivalent (e.g. linkedql.Entity or a path step)."],"exampleFix":"// before\nstep := myCustomStep{} // implements neither IteratorStep nor PathStep\nit, err := linkedql.BuildIterator(ctx, qs, ns, step) // panics-less error\n// after\nvar _ linkedql.IteratorStep = myCustomStep{} // add BuildIterator method first\nit, err := linkedql.BuildIterator(ctx, qs, ns, step)","handlingStrategy":"type-guard","validationCode":"if _, ok := step.(linkedql.IteratorStep); !ok {\n    if _, ok := step.(linkedql.PathStep); !ok {\n        return fmt.Errorf(\"step %T is not executable\", step)\n    }\n}","typeGuard":"func isExecutableStep(s query.Step) bool {\n    _, it := s.(linkedql.IteratorStep)\n    _, ps := s.(linkedql.PathStep)\n    return it || ps\n}","tryCatchPattern":"it, err := linkedql.BuildIterator(ctx, qs, ns, step)\nif err != nil {\n    if err.Error() == \"must execute a IteratorStep or PathStep\" {\n        return fmt.Errorf(\"unsupported step type %T\", step)\n    }\n    return err\n}","preventionTips":["Compile-time assertions: var _ linkedql.IteratorStep = (*MyStep)(nil)","Only construct steps via linkedql's registry/constructors","Validate decoded query JSON against known step types before execution"],"tags":["go","linkedql","iterator","unsupported-type"],"backgroundTag":"unsupported-operation","analyzedSha":"81dcd7d73e45136bc0d01802a8ba4685d8a533eb","analyzedAt":"2026-09-06T06:14:12.358Z","contentChangedAt":"2026-09-06T06:14:12.358Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}