---
id: troubleshooting.output-mapping
title: Output mapping troubleshooting
summary: Fix external output rows that do not join cleanly to immutable Case IDs in an output-only Run.
kind: error
product_area: troubleshooting
status: stable
updated: 2026-08-23
canonical: /docs/troubleshooting/output-mapping
---

# Output mapping troubleshooting

Use this when externally produced responses exist but the mapping preview cannot join them cleanly to the Cases in the selected Benchmark Version.

## Symptom

Rows are unmatched, duplicated, or mapped to the wrong Case ID, or the wrong column was selected as the response. No output-only Run should be trusted until the mapping preview is correct.

## Likely causes

- External rows use row order or display text instead of immutable Case IDs.
- The file contains Case IDs from another Benchmark Version or Dataset export.
- The selected response column or identifier column is wrong.
- Several candidate output sets were combined without distinct metadata.

## Diagnostic checks

- Compare several affected case IDs with the output source IDs.
- Check whether the output set has candidate metadata such as model, prompt, retrieval version, or run identity.
- Confirm the source file was produced from the same immutable Case population.
- Inspect duplicate, blank, and unknown identifier counts in the mapping preview.

## Fix

- Correct the external file and map using immutable Case IDs rather than row position.
- Select the intended response column and keep one candidate output set per output-only Run.
- Create a new output-only Run from the corrected mapping. Existing Runs remain evidence under their original mapping.
- Repair missing Case context through the Case workflow, not during output mapping; create a new version boundary when Case content changes.

## Prevention

- Preserve source IDs through import and output generation.
- Sample mapped outputs before expert contribution work and before Evaluation Runs.
- Keep candidate identity in run metadata.
- Treat each imported output-only Run as its own evidence record; it is not a saved Harness Version.

## Related task pages

{% related-card-grid title="Related task pages" %}
- [Importing cases](/docs/operating-manual/import-and-prepare-cases)
- [Map external outputs](/docs/benchmark-evaluations/output-mapping)
- [Inspect evaluation results](/docs/benchmark-evaluations/inspect-results)
{% /related-card-grid %}

## Related reference pages

{% related-card-grid title="Related reference pages" %}
- [Target model outputs](/docs/object-model/outputs)
- [Represent conversations in Cases](/docs/object-model/represent-conversations-in-cases)
- [Benchmark Evaluations](/docs/benchmark-evaluations)
{% /related-card-grid %}

## Source confidence

Code-backed: the current output-mapping modal defines identifier and output-column selection, mapping preview, unmatched rows, metadata, and creation of an output-only Run. The Runs workspace keeps that imported evidence distinct from saved Harness Versions.