{"record":{"id":"6afac1d3b2a53eb0","repo":"cloudflare/cloudflared","slug":"the-cloudflare-api-response-was-an-unexpected-type","errorCode":null,"errorMessage":"the Cloudflare API response was an unexpected type","messagePattern":"the Cloudflare API response was an unexpected type","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cfapi/base_client.go","lineNumber":141,"sourceCode":"\t}\n\n\treturn &result, nil\n}\n\nfunc parseResponse(reader io.Reader, data interface{}) error {\n\tresult, err := parseResponseEnvelope(reader)\n\tif err != nil {\n\t\treturn err\n\t}\n\n\treturn parseResponseBody(result, data)\n}\n\nfunc parseResponseBody(result *response, data interface{}) error {\n\t// At this point we know the API call succeeded, so, parse out the inner\n\t// result into the datatype provided as a parameter.\n\tif err := json.Unmarshal(result.Result, &data); err != nil {\n\t\treturn errors.Wrap(err, \"the Cloudflare API response was an unexpected type\")\n\t}\n\treturn nil\n}\n\nfunc fetchExhaustively[T any](requestFn func(int) (*http.Response, error)) ([]*T, error) {\n\tpage := 0\n\tvar fullResponse []*T\n\n\tfor {\n\t\tpage += 1\n\t\tenvelope, parsedBody, err := fetchPage[T](requestFn, page)\n\n\t\tif err != nil {\n\t\t\treturn nil, errors.Wrap(err, fmt.Sprintf(\"Error Parsing page %d\", page))\n\t\t}\n\n\t\tfullResponse = append(fullResponse, parsedBody...)\n\t\tif envelope.Pagination.Count < envelope.Pagination.PerPage || len(fullResponse) >= envelope.Pagination.TotalCount {","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/cloudflare/cloudflared/blob/2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f/cfapi/base_client.go#L123-L159","documentation":"parseResponseBody unmarshals the envelope's inner 'result' field into the caller-provided datatype and wraps failures with this message. The outer envelope parsed fine and the API call succeeded, but the result payload does not match the expected Go type (e.g. an object where a list is expected, or a schema change).","triggerScenarios":"The Cloudflare API returns a result whose JSON shape doesn't match the target struct (API schema change, an error object inside result, or the caller passing the wrong type to parseResponse).","commonSituations":"Using an old cloudflared version against a newer API where the tunnel/route schema changed; passing a single-item struct when the API returns an array (or vice versa).","solutions":["Log result.Result raw JSON and compare it to the destination struct's fields/tags.","Upgrade cloudflared/cfapi to the latest version to pick up API schema changes.","Ensure the generic type parameter passed to parseResponse matches the endpoint's result shape.","Check the Cloudflare API changelog for recent changes to the tunnel/teamnet endpoints."],"exampleFix":"// before\nvar result []cfapi.Route\n// after (single-object endpoint)\nvar result cfapi.Route","handlingStrategy":"type-guard","validationCode":"var probe map[string]json.RawMessage\nif err := json.Unmarshal(raw, &probe); err != nil {\n\treturn fmt.Errorf(\"result is not an object: %w\", err)\n}\nif _, ok := probe[\"result\"]; !ok {\n\treturn errors.New(\"envelope missing result field\")\n}","typeGuard":"func isEnvelope(obj map[string]any) bool {\n\t_, hasSuccess := obj[\"success\"]\n\t_, hasResult := obj[\"result\"]\n\treturn hasSuccess && hasResult\n}","tryCatchPattern":"if err := client.SomeCall(t); err != nil {\n\tif strings.Contains(err.Error(), \"unexpected type\") {\n\t\treturn fmt.Errorf(\"cfapi schema mismatch; upgrade cloudflared: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Keep cloudflared/cfapi updated with API schema changes.","Match the destination type to the endpoint's documented result shape (object vs array).","Log raw result JSON when debugging schema mismatches."],"tags":["go","json","api-client","schema"],"backgroundTag":"unexpected-response-shape","analyzedSha":"2253eeeb25a44a713a4b60b8ba1e1b3f377d1a0f","analyzedAt":"2026-09-06T04:14:33.757Z","contentChangedAt":"2026-09-06T04:14:33.757Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}