weaviate/weaviate · error

prepare export

Error message

prepare export: %w

What it means

This is the wrapper error returned by the cluster-internal HTTP endpoint that prepares (starts) a streaming export on a participating node. The handler calls the export participant, and if starting fails it writes the wrapped error to the HTTP response with a status code chosen by error identity: 409 if the error is export.ErrExportAlreadyActive, 400 if it is export.ErrExportValidation, otherwise the default 500. It exists so the coordinating node receives a descriptive reason why a node refused to prepare an export.

Solutions

  1. If you got 409, wait for or cancel the currently active export on that node before starting a new one.
  2. If you got 400, check the export request payload: output location, class/shard names, and other validated fields.
  3. Check the node's logs and filesystem permissions for the export output path for non-409/400 failures.
  4. Retry the prepare call after resolving the underlying cause; the error is returned per-node so identify the failing node from the response.

Example fix

// caller checks status before retrying
if resp.StatusCode == http.StatusConflict {
    // an export is already active; cancel or wait, then re-prepare
}
Defensive patterns

Strategy: try-catch

Validate before calling

// before calling prepare, ensure no export is active and the payload validates
active, _ := exportClient.IsActive(node)
if active {
    return fmt.Errorf("export already active on node")
}

Try / catch

resp, err := client.Post(prepareURL)
if err != nil { return err }
switch resp.StatusCode {
case http.StatusConflict:
    // wait for or cancel the active export, then retry
case http.StatusBadRequest:
    // fix the export request payload
default:
    // inspect response body ("prepare export: ...") and node logs
}

Prevention

When it happens

Trigger: POST to the clusterapi export-prepare endpoint when the node cannot start the export: another export is already active on the node (409), the export request fails validation such as invalid output path or class settings (400), or any other participant-level error such as filesystem issues (500).

Common situations: Two exports triggered concurrently against the same shard/node; an operator pointing the export at an unwritable or nonexistent output directory; a schema/class mismatch after a collection was renamed or deleted between coordination and preparation.

Related errors


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

Appendix: source

Thrown at adapters/handlers/rest/clusterapi/exports.go:101

			http.Error(w, fmt.Errorf("read request body: %w", err).Error(), http.StatusInternalServerError)
			return
		}

		var req export.ExportRequest
		if err := json.Unmarshal(body, &req); err != nil {
			http.Error(w, fmt.Errorf("unmarshal request: %w", err).Error(), http.StatusBadRequest)
			return
		}

		if err := e.participant.Prepare(r.Context(), &req); err != nil {
			status := http.StatusInternalServerError
			switch {
			case errors.Is(err, export.ErrExportAlreadyActive):
				status = http.StatusConflict
			case errors.Is(err, export.ErrExportValidation):
				status = http.StatusBadRequest
			}
			http.Error(w, fmt.Errorf("prepare export: %w", err).Error(), status)
			return
		}

		w.WriteHeader(http.StatusOK)
	}
}

func (e *exports) commitHandler() http.HandlerFunc {
	return func(w http.ResponseWriter, r *http.Request) {
		defer r.Body.Close()

		exportID := r.URL.Query().Get("id")
		if exportID == "" {
			http.Error(w, "missing 'id' query parameter", http.StatusBadRequest)
			return
		}

		if err := e.participant.Commit(r.Context(), exportID); err != nil {

View on GitHub (pinned to 75aa4b6d11)