apache/beam · error

bad SHA256 for : , want

Error message

bad SHA256 for %v: %v, want %v

What it means

Returned by artifact.retrieve when the SHA256 of the downloaded artifact does not match the expected hash recorded in the artifact's type payload. Validation runs only when artifact validation is enabled (default true via WithArtifactValidation/context). It means the artifact was corrupted or replaced in transit or at rest.

Solutions

1. Re-stage/re-submit the pipeline so artifact metadata hashes match the freshly staged content.
2. Rerun retrieval — MultiRetrieve retries, but a deterministic hash mismatch needs re-staging, not retrying.
3. Check for content-altering middleboxes (proxies, virus scanners) between worker and staging service.
4. As a last resort for known-benign mismatches, call artifact.WithArtifactValidation(ctx, false) to disable checks.

Example fix

// before: stale staged artifact reused after content changed
// re-stage and resubmit:
//   beam job submission --artifacts_dir fresh_dir
// or temporarily disable validation for debugging:
// after
ctx = artifact.WithArtifactValidation(ctx, false)

func verifyArtifactHash(path, expected string) error {
	if expected == "" { return nil }
	// compute sha256 of staged content and compare before relying on retrieval
	f, err := os.Open(path)
	if err != nil { return err }
	defer f.Close()
	h := sha256.New()
	if _, err := io.Copy(h, f); err != nil { return err }
	got := hex.EncodeToString(h.Sum(nil))
	if got != expected { return fmt.Errorf("sha256 mismatch: got %s want %s", got, expected) }
	return nil
}

if err := artifact.Materialize(ctx, endpoint, deps, rt, dest); err != nil {
	if strings.Contains(err.Error(), "bad SHA256") {
		log.Printf("artifact corrupted in transit/staging; re-staging and retrying once")
		// re-stage artifacts, then retry Materialize once
	}
	return err
}

When it happens

Trigger: Materialize downloading an artifact whose computed sha256 differs from expectedSha256 (from ArtifactFilePayload/ArtifactUrlPayload). Triggered by corrupted staging content, a re-staged artifact of the same name with different bytes, or a truncated/modified transfer that still completed.

Common situations: Artifacts re-staged between submission and retrieval while hashes went stale; flaky proxy/cache mangling content; manually edited staged files; known issue where a proxy or registry injects content. Disabling via WithArtifactValidation(ctx, false) skips the check (with a WARN when no hash is present).

Understand the failure class

Background: Checksum mismatch errors: "checksum verification failed", "digest mismatch", "expected vs actual checksum" — what they mean and how to fix them — this error's family across 41 libraries.

Related errors

• unexpected SHA256 for sent chunks for
• chunk write failed
• failed to both validate
• failed to create artifact role payload
• failed to delete: (remove: )

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/7ac816cc795b0835. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/artifact/materialize.go:261

		fd.Close() // drop any buffered content
		return errors.Wrapf(err, "failed to retrieve chunk for %v", filename)
	}
	if err := w.Flush(); err != nil {
		fd.Close()
		return errors.Wrapf(err, "failed to flush chunks for %v", filename)
	}
	stat, _ := fd.Stat()
	log.Printf("Downloaded: %v (sha256: %v, size: %v)", filename, sha256Hash, stat.Size())

	if err := fd.Close(); err != nil {
		return err
	}

	if isArtifactValidationEnabled(ctx) {
		if a.expectedSha256 == "" {
			log.Printf("WARN: Artifact validation skipped for file: %v", filename)
		} else if sha256Hash != a.expectedSha256 {
			return errors.Errorf("bad SHA256 for %v: %v, want %v", filename, sha256Hash, a.expectedSha256)
		}
	}

	return nil
}

func writeChunks(stream jobpb.ArtifactRetrievalService_GetArtifactClient, w io.Writer) (string, error) {
	sha256W := sha256.New()
	for {
		chunk, err := stream.Recv()
		if err == io.EOF {
			break
		}
		if err != nil {
			return "", err
		}
		if _, err := sha256W.Write(chunk.Data); err != nil {
			panic(err) // cannot fail

View on GitHub (pinned to 12126d8942)