{"record":{"id":"daa4913de4b455ea","repo":"larksuite/cli","slug":"jq-w","errorCode":null,"errorMessage":"jq: %w","messagePattern":"jq: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/event/consume/jq.go","lineNumber":43,"sourceCode":"\t\t\t\"jq compile error: %s\", err).WithParam(\"--jq\").WithCause(err)\n\t}\n\treturn code, nil\n}\n\n// applyJQ returns (nil, nil) when the expression filters out the event (e.g. select).\nfunc applyJQ(code *gojq.Code, data json.RawMessage) (json.RawMessage, error) {\n\tvar input interface{}\n\tif err := json.Unmarshal(data, &input); err != nil {\n\t\treturn nil, fmt.Errorf(\"jq: unmarshal input: %w\", err)\n\t}\n\n\titer := code.Run(input)\n\tv, ok := iter.Next()\n\tif !ok {\n\t\treturn nil, nil\n\t}\n\tif err, isErr := v.(error); isErr {\n\t\treturn nil, fmt.Errorf(\"jq: %w\", err)\n\t}\n\n\tresult, err := json.Marshal(v)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"jq: marshal result: %w\", err)\n\t}\n\treturn json.RawMessage(result), nil\n}\n","sourceCodeStart":25,"sourceCodeEnd":52,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/internal/event/consume/jq.go#L25-L52","documentation":"gojq iterators return errors as values: code.Run(input)'s iter.Next() yields an error value instead of a result when the jq expression fails at runtime (e.g. applying a filter to a wrong-typed value). applyJQ detects the error value and wraps it with the 'jq: %w' prefix. This is a runtime (not compile-time) jq failure — the expression compiled fine but cannot execute against this particular input.","triggerScenarios":"iter.Next() returns v that is an error inside applyJQ (internal/event/consume/jq.go:38-42) — e.g. expression like .field[0] on a non-array, arithmetic on strings/null, select on a scalar, or accessing .x.y when .x is a string.","commonSituations":"Event schema changed so the jq expression no longer matches the payload shape; filter written against a differently structured event; optional fields absent causing null-dereference-style jq errors; developer tested jq against sample data that diverges from production events.","solutions":["Make the jq expression defensive: guard types first, e.g. select(type == \"object\") or (.field // []) before indexing.","Log the wrapped gojq error together with the event key/payload to identify which events break the expression.","Update the compiled expression (compileJQ) to match the current event schema.","Decide policy: treat jq runtime failure as a filtered-out event (return nil, nil) if drop-on-error is acceptable, or keep failing loudly for a required transform."],"exampleFix":"// before: brittle expression compiled once\ncode, _ := gojq.Parse(\".items[0].id\")\n// after: defensive expression tolerant of shape changes\ncode, _ := gojq.Parse(\"(.items // [])[0].id? // empty\")","handlingStrategy":"fallback","validationCode":null,"typeGuard":"func jqIterError(v any) (error, bool) {\n    err, isErr := v.(error)\n    return err, isErr\n}","tryCatchPattern":"out, err := applyJQ(code, data)\nif err != nil {\n    if strings.HasPrefix(err.Error(), \"jq: \") {\n        log.Warnf(\"jq runtime failure on event %s: %v\", eventKey, err)\n        return fallbackTransform(data) // or drop event per policy\n    }\n    return err\n}","preventionTips":["Write jq expressions with // empty, type guards (select(type==...)), and optional chaining so schema drift degrades gracefully.","Test compiled jq expressions against real production-shaped event samples, not just ideal payloads.","Decide and document drop-on-error vs fail-loud policy per filter."],"tags":["jq","gojq","runtime-error","events"],"backgroundTag":"jq-runtime-error","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}