hasura/graphql-engine · error

decoding API response failed for: %v

Error message

decoding API response failed for: %v

What it means

Returned by GetVersion when the response body from /v1/version cannot be decoded into hasura.V1VersionResponse (a JSON object with a version field). This means the server returned HTTP 200 but the payload was not the expected JSON shape — typically HTML or an empty/garbled body.

Source

Thrown at cli/internal/hasura/v1version/version.go:50

	if err != nil {
		return nil, errors.E(op, err)
	}

	if resp.StatusCode != http.StatusOK {
		if b.Len() > 0 {
			return nil, errors.E(op, errors.KindHasuraAPI, b.String())
		} else {
			return nil, errors.E(
				op,
				errors.KindHasuraAPI,
				fmt.Errorf("API request to %v failed, code: %v", c.path, resp.StatusCode),
			)
		}
	}

	o := new(hasura.V1VersionResponse)
	if err := json.NewDecoder(b).Decode(o); err != nil {
		return nil, errors.E(op, fmt.Errorf("decoding API response failed for: %v", c.path))
	}

	return o, nil
}

func (c *Client) send(body any, responseBodyWriter io.Writer) (*httpc.Response, error) {
	var op errors.Op = "v1version.Client.send"

	req, err := c.NewRequest(http.MethodGet, c.path, body)
	if err != nil {
		return nil, errors.E(op, err)
	}

	resp, err := c.LockAndDo(context.Background(), req, responseBodyWriter)
	if err != nil {
		return nil, errors.E(op, err)
	}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Curl the URL directly and inspect the body: curl <endpoint>/v1/version — if it's HTML, the endpoint is wrong
2. Point the CLI at the actual Hasura server root URL
3. Fix ingress/proxy rules so /v1/version is passed through to Hasura unmodified

resp, err := http.Get(endpoint + "/v1/version")
if err == nil {
	defer resp.Body.Close()
	b, _ := io.ReadAll(resp.Body)
	var probe struct{ Version string `json:"version"` }
	if json.Unmarshal(b, &probe) != nil || probe.Version == "" {
		// endpoint is not serving the Hasura version JSON; fix URL/proxy
	}
}

v, err := client.GetVersion()
if err != nil {
	if strings.Contains(err.Error(), "decoding API response failed") {
		// server returned 200 with non-JSON (HTML/empty): endpoint or proxy misconfigured
	}
	return err
}

When it happens

Trigger: The /v1/version URL returns 200 with HTML (a SPA, login page, or catch-all route), an API gateway that rewrites responses, a server that returns an empty body, or a proxy serving a status page on all paths.

Common situations: Endpoint pointed at a domain where a web app catches all routes with 200 HTML, misconfigured ingress rewrite rules, or a non-Hasura service listening on the target port.

Related errors

• %s: decoding graphql response errors: %w
• %s: decoding graphql responnse data: %w
• error fetching config from server: %w
• error fetching server config: %v
• error serving console: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/3fadda3b1cdc745c. Report an issue: GitHub.