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
- If you got 409, wait for or cancel the currently active export on that node before starting a new one.
- If you got 400, check the export request payload: output location, class/shard names, and other validated fields.
- Check the node's logs and filesystem permissions for the export output path for non-409/400 failures.
- 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
- Serialize export operations per node rather than triggering them concurrently.
- Validate output paths and class settings before dispatching the prepare request.
- Track export state so stale exports are committed or cancelled promptly.
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
- commit export
- abort failed: status
- commit failed: status
- commit request
- failed to resolve hostname for node
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)