temporalio/temporal · error

failed to parse link header: %w

Error message

failed to parse link header: %w

What it means

Error "failed to parse link header: %w" thrown in temporalio/temporal.

Source

Thrown at common/nexus/nexusrpc/api.go:177

	}

	if encodedLink[0] != '<' {
		return link, fmt.Errorf("failed to parse link header: invalid format: %s", encodedLink)
	}
	urlEnd := strings.Index(encodedLink, ">")
	if urlEnd == -1 {
		return link, fmt.Errorf("failed to parse link header: invalid format: %s", encodedLink)
	}
	urlStr := strings.TrimSpace(encodedLink[1:urlEnd])
	if len(urlStr) == 0 {
		return link, errors.New("failed to parse link header: url is empty")
	}
	u, err := url.Parse(urlStr)
	if err != nil {
		return link, fmt.Errorf("failed to parse link header: invalid url: %s", urlStr)
	}
	if err := validateLinkURL(u); err != nil {
		return link, fmt.Errorf("failed to parse link header: %w", err)
	}
	link.URL = u

	params := strings.Split(encodedLink[urlEnd+1:], ";")
	// must contain at least one semi-colon, and first param must be empty since
	// it corresponds to the url part parsed above.
	if len(params) < 2 {
		return link, fmt.Errorf("failed to parse link header: invalid format: %s", encodedLink)
	}
	if strings.TrimSpace(params[0]) != "" {
		return link, fmt.Errorf("failed to parse link header: invalid format: %s", encodedLink)
	}

	typeKeyFound := false
	for _, param := range params[1:] {
		param = strings.TrimSpace(param)
		if len(param) == 0 {
			return link, fmt.Errorf("failed to parse link header: parameter is empty: %s", encodedLink)

View on GitHub (pinned to bde624efd1)

When it happens

Trigger: Thrown at common/nexus/nexusrpc/api.go:177 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

AI-assisted analysis of temporalio/temporal@bde624efd1 (2026-09-01). Data as JSON: /api/errors/4bf24019bd53ca7a. Report an issue: GitHub.