BoundaryML/baml · error

unexpected status %d fetching checksum %s

Error message

unexpected status %d fetching checksum %s

What it means

The checksum endpoint returned a status code that is neither 200 nor 404 (e.g. 500, 502, 403). downloadChecksum surfaces the status and URL in a plain error to indicate an unexpected server-side response.

Source

Thrown at engine/language_client_go/baml_go/lib_common.go:589

//orchestrion:ignore
func downloadChecksum(checksumURL string, targetFilename string) (string, error) {
	// Use uninstrumented client to avoid Orchestrion crash during init()
	//orchestrion:ignore
	httpClient := uninstrumentedHTTPClient()
	//orchestrion:ignore
	resp, err := httpClient.Get(checksumURL)
	if err != nil {
		return "", fmt.Errorf("network error fetching checksum %s: %w", checksumURL, err)
	}
	defer resp.Body.Close()

	if resp.StatusCode == http.StatusNotFound {
		logger.Debug("Checksum file not found (404)", "url", checksumURL)
		return "", fmt.Errorf("checksum file not found (404)")
	}
	if resp.StatusCode != http.StatusOK {
		return "", fmt.Errorf("unexpected status %d fetching checksum %s", resp.StatusCode, checksumURL)
	}

	bodyBytes, err := io.ReadAll(io.LimitReader(resp.Body, 4096))
	if err != nil {
		return "", fmt.Errorf("error reading checksum body %s: %w", checksumURL, err)
	}

	lines := strings.Split(string(bodyBytes), "\n")
	for _, line := range lines {
		parts := strings.Fields(line)
		if len(parts) >= 2 {
			checksum, filenameInLine := parts[0], strings.TrimPrefix(parts[1], "*")
			if filenameInLine == targetFilename {
				if len(checksum) == 64 && isHex(checksum) {
					logger.Debug("Found matching checksum in file", "filename", targetFilename, "checksum", checksum)
					return checksum, nil
				}
				logger.Warn("Invalid checksum format found in checksum file",

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Check the artifact server status; retry after transient 5xx
2. Inspect whether a WAF/CDN blocks your user agent or IP (403) and adjust headers/proxy
3. Add retry with backoff around checksum/download in CI
4. Verify the checksum URL endpoint is still valid after infrastructure changes

var cs string
var err error
for i := 0; i < 3; i++ {
    cs, err = downloadChecksum(url, name)
    if err == nil || !strings.Contains(err.Error(), "unexpected status") { break }
    time.Sleep(time.Duration(1<<i) * time.Second)
}

When it happens

Trigger: httpClient.Get(checksumURL) returns a response with an unexpected status such as 403 Forbidden (blocked by CDN/WAF), 500, or 503 from the artifact server.

Common situations: CDN or WAF blocking the request from CI environments, upstream server outage returning 5xx, or rate limiting by the distribution host.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• LLM client "{client_name}" failed with status code: {status_
• network error fetching checksum %s: %w
• error reading checksum body %s: %w
• {kind} artifact failed integrity validation
• Auth server returned {status}: {body}

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/63e0a526d930eb97. Report an issue: GitHub.