Skip to content
Merulan

Promote and troubleshoot

Promote a checked Pipeline version, read the result, and choose recovery from the Run's retained evidence.

Use this guide when you are ready to promote Records with Data Pipelines or a Run needs repair. As an operator, you read the Run to check the write. Its evidence tells you what to repair.

Before you start

The Pipeline you plan to promote needs a saved version, valid targets, and a preview whose errors you have reviewed. Confirm the input, target identity, and write policy with the Pipeline model. For an existing Run, retain its handle. If the start response was uncertain, recover that request before starting different work. Request identity explains the distinction between a replay and a new Run.

Check the version

In the Pipeline builder, inspect the version and input that you intend to promote. Revalidate after a mapping, Source binding, or Company Schema change. Review row errors and any staged candidates. A successful preview does not approve every candidate or prove a write. Select promotion only when the target's identity and write policy describe the changes you intend.

Start promotion

In the upload builder, choose Promote for the checked CSV. An eligible prepared Pipeline with installed Sources has a separate launch control. Use that control when it is offered and its gate is ready. The Run result provides the handle to keep. A response that admits the Run is the start of readback, not proof that Records were written.

For an API caller, follow the start contract with a stable request key. Use the API guide for access and syntax. MCP can start this operation, but Run readback requires the API or Console.

Read the result

Open the Run in the Console or use Read a Run with its handle. Inspect the status, mode, counts, errors, and report for the promoted output. Follow lineage to the version and inputs when a result needs explanation. If the Run is still active, continue reading that Run. Do not infer completion from a notification or elapsed time.

Checkpoints

The Pipeline version and input must match the reviewed work. The Run handle must identify the accepted request. After execution, compare the promoted and refused counts with the expected rows. Inspect refused rows before calling the load complete. A partial_failure result needs the successful part preserved and the failed part explained. It cannot be read as an empty write.

Success

The Run has settled, and its counts and artifacts account for the promoted Records. Inspect those Records when you need to confirm field values or history. A completed preview is not this terminal. For candidate review, use the accepted candidate's promotion result and effect reference to confirm the write. Keep the Run and version as evidence for later investigation.

When it fails

A Run that fails to promote needs its error and status read back. Read retained evidence before changing the Pipeline or issuing another start.

DATA_PIPELINES_REQUEST_IDENTITY_CONFLICT

The key already names different work. Recover the original request with its unchanged inputs. Use another key only when you intend a different Run.

VALIDATION_FAILED

The requested start or recovery is invalid for this Pipeline. Correct the named input, version, or target. Revalidate before attempting the write again.

pipeline_run_aborted

The Run stopped on a system failure. Inspect its message, counts, and artifacts. Repair the failed input or service condition before choosing a retry.

Recovery

A settled failed, partial_failure, or cancelled Run can offer Retry run in the Console. Retry uses the prior Run as its basis and reuses eligible successful node work. Read the retry's returned handle to confirm its result. If the mapping changed, use the corrected Pipeline version for new work instead of treating it as the old request.

For an active Run you intend to stop, choose Cancel run. Cancellation is a request until readback says cancelled. The stopped Run cannot promote. A lost start response needs an unchanged keyed replay, not a failed-Run retry.

Next steps