No `jq_schema` nor `content_key` specified. Set either or bo

Error message

No `jq_schema` nor `content_key` specified. Set either or both to extract data.

What it means

JSONConverter needs at least one extraction strategy: a jq_schema (a jq-style filter) or a content_key (a direct key to pull from each JSON object). If the compiled jq filter is absent and content_key is None, there is nothing to extract, so __init__ raises ValueError immediately at component construction time.

Source

Thrown at haystack/components/converters/json.py:150

            An optional set of meta keys to extract from the content.
            If `jq_schema` is specified, all keys will be extracted from that object.
        :param store_full_path:
            If True, the full path of the file is stored in the metadata of the document.
            If False, only the file name is stored.
        """
        self._compiled_filter = None
        if jq_schema:
            jq_import.check()
            self._compiled_filter = jq.compile(jq_schema)

        self._jq_schema = jq_schema
        self._content_key = content_key
        self._meta_fields = extra_meta_fields
        self._store_full_path = store_full_path

        if self._compiled_filter is None and self._content_key is None:
            msg = "No `jq_schema` nor `content_key` specified. Set either or both to extract data."
            raise ValueError(msg)

    def to_dict(self) -> dict[str, Any]:
        """
        Serializes the component to a dictionary.

        :returns:
            Dictionary with serialized data.
        """
        return default_to_dict(
            self,
            jq_schema=self._jq_schema,
            content_key=self._content_key,
            extra_meta_fields=self._meta_fields,
            store_full_path=self._store_full_path,
        )

    @classmethod
    def from_dict(cls, data: dict[str, Any]) -> "JSONConverter":

View on GitHub (pinned to e318778c9b)

Solutions

Pass content_key='your_key' to extract the value under that key
Pass jq_schema='.' or a specific filter like jq_schema='[].name'
If you intended a no-op conversion, use a different component

Example fix

// before
converter = JSONConverter()
// after
converter = JSONConverter(jq_schema=".content", content_key="text")

Defensive patterns

Strategy: validation

Validate before calling

def make_json_converter(jq_schema=None, content_key=None, **kw):
    if jq_schema is None and content_key is None:
        raise ValueError("Provide jq_schema or content_key")
    return JSONConverter(jq_schema=jq_schema, content_key=content_key, **kw)

Try / catch

try:
    converter = JSONConverter()
except ValueError as e:
    converter = JSONConverter(content_key="text")

Prevention

Always pass either jq_schema or content_key when constructing JSONConverter
Test component construction in unit tests to fail fast on config regressions
Check serialized YAML for empty init_parameters after refactors

When it happens

Trigger: Instantiating JSONConverter() with neither jq_schema nor content_key, e.g. JSONConverter() or JSONConverter(extra_meta_fields=[...]) only.

Common situations: Copy-pasting a JSONConverter init and deleting the parameters; serializing/deserializing YAML where both params were left blank; assuming a default extraction exists when it does not.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

AI-assisted analysis of deepset-ai/haystack@e318778c9b (2026-08-30). Data as JSON: /api/errors/72f548656b3e32f8. Report an issue: GitHub.