salesforce INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST when agent sets lead source to a value that doesn't exist

TL;DR

Read the live picklist values from the field's describe result before writing, and map the agent's intended value to an existing entry. Never hardcode picklist strings. If the value is legitimate but missing, have it added in setup first, then retry the write.

salesforce INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST when agent sets lead source to a value that doesn't exist

Steps

1. Describe the LeadSource field (or the failing field) and pull the current list of allowed values. Expected: you have the exact valid entries, including casing.
2. Map the agent's intended value to the closest valid entry; if nothing matches, fail loudly instead of guessing. Expected: writes use only values from the live list.
3. Keep the value map in config and refresh it on a schedule so retired or renamed values do not rot. Expected: a renamed picklist value is picked up at the next refresh, not at the next failure.
4. If the business genuinely needs a new value, get it added in setup, then retry. Expected: the write succeeds once the value exists in the org.

Use this when

• lead source writes fail with INVALIDORNULLFORRESTRICTED_PICKLIST
• the agent sets a picklist value that worked last month but fails now
• casing or spacing differences between the agent's value and the org's value

Not for this skill when

• unrestricted picklists - those accept anything, so the error cannot occur there
• plain text fields - no value list to violate
• values hidden by record-type scoping - that needs the record type fixed, not the value

Variant phrasings

restricted picklist value does not exist

Same root cause: the value is not in the org's defined set.

lead source rejected on write

Same fix: describe first, map to a live value.

invalid picklist value from the agent

Same fix: never hardcode; read the allowed list.

Why it happens

Restricted picklists reject anything not in their defined value set, and the check is exact - casing and spacing included. The agent either invented a plausible value, carried one over from a different org, or kept using one that an admin renamed or retired. The API validates at write time, so the failure surfaces far from where the bad value was chosen.

Edge cases

• Record types can scope which values are available - describe the field in the context of the record type being written.
• API names and labels can differ - write the API name, not the display label.
• Dependent picklists add a second axis - validate the controlling field's value too.

Provenance

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