What causes "write files for shard %q: %w" in weaviate/weaviate?

Read the wrapped inner error to distinguish source-read vs destination-write failure.

write files for shard %q: %w

Error message

write files for shard %q: %w

What it means

Wraps a failure from zip.WriteShard, which packages a shard's files into a zip chunk for upload. This is the normal (non-split) path of per-shard backup writing; any read/compress/write failure while packaging shard files surfaces with the shard name attached.

Source

Thrown at usecases/backup/backend.go:721

		}()

		if err := ctx.Err(); err != nil {
			return nil, err
		}

		var fileSizeExceededInfo *SplitFile
		if fileSizeExceededWrite != nil {
			// Only write the split file part in this chunk; remaining space is intentionally
			// left unused to keep the logic simple and avoid mixing split file parts with
			// regular files in the same chunk.
			fileSizeExceededInfo, err = zip.WriteSplitFile(ctx, shard, fileSizeExceededWrite, &preCompressionSize, chunkKey)
			if err != nil {
				return nil, fmt.Errorf("write split file for shard %q: %w", shard.Name, err)
			}
		} else {
			_, fileSizeExceededInfo, err = zip.WriteShard(ctx, shard, filesInShard, firstChunkForShard, &preCompressionSize, chunkKey)
			if err != nil {
				return nil, fmt.Errorf("write files for shard %q: %w", shard.Name, err)
			}
		}
		shard.ClearTemporary()

		if zip.compressorWriter != nil {
			if err := zip.compressorWriter.Flush(); err != nil {
				return nil, fmt.Errorf("flush compressor: %w", err)
			}
		}

		return fileSizeExceededInfo, nil
	}

	// consumer
	eg.Go(func() error {
		if _, err := u.backend.Write(ctx, chunkKey, overrideBucket, overridePath, reader); err != nil {
			u.log.WithFields(logrus.Fields{
				"chunkKey": chunkKey,

View on GitHub (pinned to 75aa4b6d11)

Solutions

Read the wrapped inner error to distinguish source-read vs destination-write failure.
Retry the backup after confirming no competing process is mutating the shard's staging files.
Check destination bucket permissions/quota and network stability.
Check disk health on the node hosting the shard (dmesg, SMART) if inner error indicates I/O errors.

Defensive patterns

Strategy: retry

Validate before calling

// preflight destination write probe
if err := probeDestinationWrite(bucket); err != nil {
    return fmt.Errorf("destination not writable: %w", err)
}

Try / catch

if err := runBackup(ctx); err != nil {
    var netErr net.Error
    if strings.Contains(err.Error(), "write files for shard") && errors.As(err, &netErr) {
        err = runBackup(ctx) // transient destination error, retry
    }
}

Prevention

Avoid mutating collections heavily during backups.
Check destination bucket health/permissions before large backups.
Watch node disk health for source-read failures.

When it happens

Trigger: Backup create API on a shard whose files are read, zipped, and written via WriteShard and the write fails — file disappeared mid-read, corrupt file, or destination write error.

Common situations: Backing up while the underlying shard data path is modified (torn read), disk errors on the source, or destination backend rejecting the chunk (S3 5xx, permissions, exhausted space).

Related errors

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/dd5bfa5e4329ffe5. Report an issue: GitHub.