hashicorp/terraform · error

{r.Status}

Error message

{r.Status}

What it means

Fallback error from decodeErrorPayload() when the response body cannot be JSON-decoded or the decoded JSON:API payload has no errors array. In that case the raw HTTP status line (e.g. '500 Internal Server Error') is returned as the error so the caller still sees something meaningful.

Source

Thrown at internal/cloud/backend_common.go:758

	case 404:
		return tfe.ErrResourceNotFound
	}

	errs, err = decodeErrorPayload(r)
	if err != nil {
		return err
	}

	return errors.New(strings.Join(errs, "\n"))
}

func decodeErrorPayload(r *http.Response) ([]string, error) {
	// Decode the error payload.
	var errs []string
	errPayload := &jsonapi.ErrorsPayload{}
	err := json.NewDecoder(r.Body).Decode(errPayload)
	if err != nil || len(errPayload.Errors) == 0 {
		return errs, errors.New(r.Status)
	}

	// Parse and format the errors.
	for _, e := range errPayload.Errors {
		if e.Detail == "" {
			errs = append(errs, e.Title)
		} else {
			errs = append(errs, fmt.Sprintf("%s\n\n%s", e.Title, e.Detail))
		}
	}

	return errs, nil
}

func isValidAppName(name string) bool {
	return name == "HCP Terraform" || name == "Terraform Enterprise"
}

View on GitHub (pinned to c9def3e214)

Solutions

1. Inspect the HTTP status code embedded in the message to classify the failure.
2. Verify the request is reaching HCP/TFE and not being intercepted by a proxy returning HTML.
3. Retry transient 5xx gateway errors; report persistent ones with the status code to platform admins.
4. Check TF_LOG=TRACE output to see the full response body that failed to decode.

if err := b.readRedactedPlan(ctx, u, token, planID); err != nil {
    // err.Error() is the raw HTTP status line, e.g. "502 Bad Gateway".
    if strings.Contains(err.Error(), "5") || strings.Contains(err.Error(), "Gateway") {
        // likely transient proxy/gateway error — retry with backoff
    }
    return err
}

When it happens

Trigger: An HCP/TFE API response with a non-2xx status whose body is empty, HTML (proxy error page), or malformed JSON — e.g. a corporate proxy returning its own error page, or a gateway timeout.

Common situations: Misconfigured egress proxy returning HTML; upstream gateway/CDN error; truncated response; non-JSON error from a middleware layer.

Related errors

• {joined API error payload}
• your version of Terraform Enterprise does not support key-va
• operation timed out
• error updating workspace %q tags: %w
• %s returned an unexpected error: %s

AI-assisted analysis of hashicorp/terraform@c9def3e214 (2026-08-07). Data as JSON: /api/errors/fcbf7f43e1e92aec. Report an issue: GitHub.