getredash/redash · warning · QueryParseError

Query must include 'url' option.

Error message

Query must include 'url' option.

What it means

After confirming the query is a dict, _run_json_query checks for the mandatory 'url' key; without it there is nothing to fetch, so it raises QueryParseError("Query must include 'url' option.").

Source

Thrown at redash/query_runner/json_ds.py:173

        pass

    def run_query(self, query, user):
        query = parse_query(query)

        data, error = self._run_json_query(query)
        if error is not None:
            return None, error

        if data:
            return data, None
        return None, "Got empty response from '{}'.".format(query["url"])

    def _run_json_query(self, query):
        if not isinstance(query, dict):
            raise QueryParseError("Query should be a YAML object describing the URL to query.")

        if "url" not in query:
            raise QueryParseError("Query must include 'url' option.")

        method = query.get("method", "get")
        request_options = project(query, ("params", "headers", "data", "auth", "json", "verify"))

        fields = query.get("fields")
        path = query.get("path")

        if "pagination" in query:
            pagination = RequestPagination.from_config(self.configuration, query["pagination"])
        else:
            pagination = None

        if isinstance(request_options.get("auth", None), list):
            request_options["auth"] = tuple(request_options["auth"])
        elif self.configuration.get("username") or self.configuration.get("password"):
            request_options["auth"] = (self.configuration.get("username"), self.configuration.get("password"))

        if method not in ("get", "post"):

View on GitHub (pinned to ca79fe988d)

Solutions

1. Add a top-level url: <full URL> key
2. Check spelling/case and that url is at column 0 (not nested under another key)

Example fix

# before
method: post
params:
  q: redash
# after
url: https://api.example.com/search
method: post
params:
  q: redash

import yaml

def has_url_key(q: str) -> bool:
    parsed = yaml.safe_load(q)
    return isinstance(parsed, dict) and "url" in parsed

def is_valid_json_ds_query(q: str) -> bool:
    try:
        parsed = yaml.safe_load(q)
    except yaml.YAMLError:
        return False
    return isinstance(parsed, dict) and "url" in parsed

When it happens

Trigger: A YAML mapping that sets only method/params/pagination/fields but omits url, typically due to a typo (Url:, uri:, endpoint:) or an over-edited example.

Common situations: Copying template queries and deleting the url line, renaming keys, indentation placing url under another key so it's not top-level.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Query is empty.
• Query should be a YAML object describing the URL to query.
• 'fields' needs to be a list.
• 'pagination' should be an object with a `type` property
• Couldn't find path {} in response.

AI-assisted analysis of getredash/redash@ca79fe988d (2026-08-28). Data as JSON: /api/errors/104c05fac284ce24. Report an issue: GitHub.