primary_output_missing: your schema passed but the key is empty

What the error means

primary_output_missing is a Format run failure with a narrow cause. The run produced a result that satisfied your output_schema, but the primary_output_key you named is empty. The partial result is on output. The run is failed, so primary_output_url is null.

The recommended action in Sume's error table is to continue the run to fill the gap, or retry. Because the schema itself was fine, rewriting the schema is not the first thing to try.

Why a valid schema can still fail

Two request fields do different jobs. output_schema shapes the whole output object. primary_output_key names one key inside it, and its URL becomes primary_output_url. The key can be up to 64 characters.

A schema can allow a nullable media field. The run can then fill every other field and leave the nullable one empty. The schema is satisfied, and the headline deliverable is still absent. That is this error.

Make the schema honest

Require only what the Format actually makes. If your key is a video and the Format sometimes ends with only stills, the empty primary key is telling you the truth. Decide whether the downstream job can accept a still, and if not, treat the failure as a retry.

Use SumeMediaFile# for media fields so Sume can check each URL against media the run really produced. Every property must be listed in required, so optional means a nullable union on that field, such as ["string", "null"].

The retry path

Continue when the run left real artifacts: the continuation sees what the first run produced and can fill the one missing piece. Retry from scratch when nothing usable was made. In both cases send a new Idempotency-Key, because the old key is bound to the failed receipt.

Before you retry, compare usage.billable_amount_usd_micros with usage.generation_spend_cap_usd_micros. A run that tried to spend more than its cap ends with the generic format_run_failed, which can look like a missing deliverable from the outside.

• Test primary_output_url, not the status alone, to know if the deliverable exists.
• Read output_error before you read output.
• Log request_id from the receipt for support.

A worked reading of the receipt

Suppose you bind a schema with two media fields, full_video and thumbnail, and name full_video as the primary key. The run finishes, fills thumbnail, and leaves full_video empty. The receipt shows status: failed, error.code: primary_output_missing, primary_output_url: null, and an output object that still holds the thumbnail. Your downstream job must not publish that thumbnail alone as if it were the deliverable.

Read three things in order. First error.code, to know the class. Second output_error, which carries { code, message, details } when the run could not produce output cleanly. Third artifacts[], to see whether a video file exists on the thread even though the key is empty. If a file exists, a continuation that says which file to place in full_video is the cheapest fix.

The same rules apply to a bulk queue. The queue item says only format_run_failed, so fetch the child receipt before you decide between continue and retry.