larksuite/cli · error

jq: %w

Error message

jq: %w

What it means

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.

Source

Thrown at internal/event/consume/jq.go:43

			"jq compile error: %s", err).WithParam("--jq").WithCause(err)
	}
	return code, nil
}

// applyJQ returns (nil, nil) when the expression filters out the event (e.g. select).
func applyJQ(code *gojq.Code, data json.RawMessage) (json.RawMessage, error) {
	var input interface{}
	if err := json.Unmarshal(data, &input); err != nil {
		return nil, fmt.Errorf("jq: unmarshal input: %w", err)
	}

	iter := code.Run(input)
	v, ok := iter.Next()
	if !ok {
		return nil, nil
	}
	if err, isErr := v.(error); isErr {
		return nil, fmt.Errorf("jq: %w", err)
	}

	result, err := json.Marshal(v)
	if err != nil {
		return nil, fmt.Errorf("jq: marshal result: %w", err)
	}
	return json.RawMessage(result), nil
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Make the jq expression defensive: guard types first, e.g. select(type == "object") or (.field // []) before indexing.
2. Log the wrapped gojq error together with the event key/payload to identify which events break the expression.
3. Update the compiled expression (compileJQ) to match the current event schema.
4. 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.

Example fix

// before: brittle expression compiled once
code, _ := gojq.Parse(".items[0].id")
// after: defensive expression tolerant of shape changes
code, _ := gojq.Parse("(.items // [])[0].id? // empty")

func jqIterError(v any) (error, bool) {
    err, isErr := v.(error)
    return err, isErr
}

out, err := applyJQ(code, data)
if err != nil {
    if strings.HasPrefix(err.Error(), "jq: ") {
        log.Warnf("jq runtime failure on event %s: %v", eventKey, err)
        return fallbackTransform(data) // or drop event per policy
    }
    return err
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• jq: unmarshal input: %w
• event catalog rejected:
• schema spec has neither Type nor Raw
• preparation strategy %q is not registered
• jq: marshal result: %w

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/daa4913de4b455ea. Report an issue: GitHub.