## TL;DR

Data Loader upsert needs a field flagged as External ID (and ideally Unique) to match on. If the field lacks the flag, or the CSV maps to the wrong field, every row fails or mismatches. Verify the field flags in Setup, map the CSV column to that exact field, and re-run.

## Error

```text
Data Loader error: Invalid external id field specified for upsert.
```

## Steps

1. In Setup, open the field definition and confirm both External ID and Unique are checked. Expected: the flags are present.
2. In Data Loader's mapping, confirm the CSV's key column maps to that field's API name. Expected: exact API name match.
3. Check the CSV key values for blanks and duplicates. Expected: every row has a distinct, non-blank key.
4. Re-run the upsert. Expected: rows match existing records or insert cleanly.
5. For recurring loads, save the mapping file. Expected: the next run maps correctly automatically.

## When to use

- Data Loader upsert fails naming the external id.
- An agent-driven CSV upsert mismatches rows.
- First upsert against a new external id field.

## When not to use

- DUPLICATE_VALUE on upsert (key collision in data, different fix).
- API upserts in code (same concept, different tooling).

## Tool compatibility

- Salesforce Data Loader (and dataloader.io) upsert operation.
- External id field definitions.

## Variant phrasings

### Invalid external id field for upsert

The field lacks the flag; set it in Setup.

### upsert matched zero rows unexpectedly

The key values do not match; check the data, not just the field.

## Why it happens

Upsert matching is only as good as the key. Without the External ID flag Salesforce cannot use the field for matching, and without uniqueness the match is ambiguous.

## Edge cases

- Marking a field External ID on an object with existing duplicate values fails; dedupe first.
- Case-insensitive unique fields need case-normalized keys in the CSV.
- Formula fields cannot be external ids; use a real stored field.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_HJDp9cihvt0RAG1P1lIacA