{"record":{"id":"b3070d2d909d497c","repo":"cayleygraph/cayley","slug":"must-execute-a-step","errorCode":null,"errorMessage":"must execute a Step","messagePattern":"must execute a Step","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"query/linkedql/linkedql.go","lineNumber":56,"sourceCode":"}\n\n// NewSession creates a new Session.\nfunc NewSession(qs graph.QuadStore) *Session {\n\treturn &Session{\n\t\tqs: qs,\n\t}\n}\n\n// Execute for a given context, query and options return an iterator of results.\nfunc (s *Session) Execute(ctx context.Context, query string, opt query.Options) (query.Iterator, error) {\n\titem, err := Unmarshal([]byte(query))\n\tif err != nil {\n\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":38,"sourceCodeEnd":71,"githubUrl":"https://github.com/cayleygraph/cayley/blob/81dcd7d73e45136bc0d01802a8ba4685d8a533eb/query/linkedql/linkedql.go#L38-L71","documentation":"linkedql.Execute takes a deserialized JSON-LD query document, converts it, and requires the result to implement the linkedql.Step interface before it can build an iterator. If the decoded item is not a Step (e.g. it is a plain document, a Document/Query wrapper, or an unknown/misspelled @type), the type assertion fails and this error is returned. It signals that the value passed to Execute is not an executable query step.","triggerScenarios":"Calling linkedql.Execute(ctx, qs, item) where item, after FromJSON/decoding, is not a Step — e.g. passing a raw map[string]interface{} document instead of the parsed step, a query document whose @type is not a registered step, or the output of a wrapper type rather than a step.","commonSituations":"Loading JSON-LD query files with an unregistered or misspelled @type; passing the top-level query envelope instead of the contained step to Execute; version drift where a step type was renamed or removed so it no longer deserializes to a Step; hand-constructing query objects without going through the step builders.","solutions":["Parse the query document with linkedql.FromJSON (or the step builders) so the value is a Step before calling Execute.","Verify the @type in the JSON-LD document matches a registered linkedql step name.","If passing code-built queries, use constructors like linkedql.NewVertex, linkedql.Out, etc., instead of raw structs/maps.","Check your linkedql/vocabulary version matches the documents you are loading (renamed or removed step types)."],"exampleFix":"// before\nvar doc map[string]interface{}\njson.Unmarshal(data, &doc)\nit, err := linkedql.Execute(ctx, qs, doc)\n// after\nstep, err := linkedql.FromJSON(data)\nif err != nil { return err }\nit, err := linkedql.Execute(ctx, qs, step)","handlingStrategy":"type-guard","validationCode":"step, err := linkedql.FromJSON(data)\nif err != nil {\n    return fmt.Errorf(\"query document is not a valid linkedql step: %w\", err)\n}","typeGuard":"if _, ok := item.(linkedql.Step); !ok {\n    return fmt.Errorf(\"item of type %T is not a linkedql.Step; parse with linkedql.FromJSON first\", item)\n}","tryCatchPattern":"it, err := linkedql.Execute(ctx, qs, step)\nif err != nil {\n    if err.Error() == \"must execute a Step\" {\n        return fmt.Errorf(\"query document @type %q is not a registered step: %w\", docType, err)\n    }\n    return err\n}","preventionTips":["Always construct query values via linkedql.FromJSON or the linkedql step builders, never raw maps.","Validate JSON-LD @type values against the registered step names for your linkedql version.","Keep the vocabulary/linkedql package version in sync with stored query documents."],"tags":["query","linkedql","type-mismatch","json-ld"],"backgroundTag":"type-mismatch","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"}