weaviate/weaviate · error

marshal merge document: %w

Error message

marshal merge document: %w

What it means

This error wraps a json.Marshal failure on the *objects.MergeDocument before it is sent via the gRPC MergeObject replication RPC (adapters/clients/replication_grpc.go:133). JSON encoding of a merge document should rarely fail since it is mostly JSON-native types, so this usually indicates unsupported values embedded in the document. The write is aborted before any network traffic.

Source

Thrown at adapters/clients/replication_grpc.go:133

	})
	if err != nil {
		return replica.SimpleResponse{}, fmt.Errorf("gRPC PutObjects: %w", err)
	}

	return protoToSimpleResponse(resp.GetResponse()), nil
}

func (c *grpcReplicationClient) MergeObject(ctx context.Context, host, index, shard, requestID string,
	doc *objects.MergeDocument, schemaVersion uint64,
) (replica.SimpleResponse, error) {
	client, err := c.getClient(host)
	if err != nil {
		return replica.SimpleResponse{}, err
	}

	mergeData, err := json.Marshal(doc)
	if err != nil {
		return replica.SimpleResponse{}, fmt.Errorf("marshal merge document: %w", err)
	}

	ctx, cancel := context.WithTimeout(ctx, COMMIT_TIMEOUT_VALUE*time.Second)
	defer cancel()

	resp, err := client.MergeObject(ctx, &protocol.MergeObjectRequest{
		Index:         index,
		Shard:         shard,
		RequestId:     requestID,
		SchemaVersion: schemaVersion,
		MergeDocument: mergeData,
	})
	if err != nil {
		return replica.SimpleResponse{}, fmt.Errorf("gRPC MergeObject: %w", err)
	}

	return protoToSimpleResponse(resp.GetResponse()), nil
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

1. Read the wrapped error to identify the offending field/type.
2. Validate the MergeDocument's properties contain only JSON-serializable types before replication.
3. Reject unserializable values at the REST/gRPC API layer with a 400 instead of reaching replication.
4. If a module injects non-serializable values, fix the module's property conversion.

Example fix

// before
mergeData, err := json.Marshal(doc)
if err != nil {
    return replica.SimpleResponse{}, fmt.Errorf("marshal merge document: %w", err)
}
// after
mergeData, err := json.Marshal(doc)
if err != nil {
    return replica.SimpleResponse{}, usecases.NewErrInvalidUserInput("invalid merge document: %v", err)
}

func validateMergeDocumentSerializable(doc *objects.MergeDocument) error {
    if doc == nil {
        return errors.New("merge document is nil")
    }
    // json.Marshal as a pre-flight check at the API layer
    if _, err := json.Marshal(doc); err != nil {
        return fmt.Errorf("merge document not JSON-serializable: %w", err)
    }
    return nil
}

mergeData, err := json.Marshal(doc)
if err != nil {
    return replica.SimpleResponse{}, fmt.Errorf("marshal merge document: %w", err)
}

When it happens

Trigger: Calling MergeObject with a MergeDocument containing values that encoding/json cannot serialize — e.g. channels, funcs, cyclic structures in custom property payloads, NaN/Inf floats in a struct marshaled via json (depending on codec), or an invalid underlying patch representation.

Common situations: Application inserting exotic property values through a programmatic client path; a module or custom extension injecting non-JSON-serializable data into the merge document; corruption in internally built merge patches.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• encode async-checkpoint create body: %w
• encode async-checkpoint delete body: %w
• marshal references: %w
• marshal request: %w
• marshal request: %w

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