Fix Salesforce Restricted Picklist Error: AI-Assisted Audit

Executive Summary

The error INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST, shown in the interface as "bad value for restricted picklist field", means Salesforce received a value that the field, record type or dependency does not allow for that operation. The SOAP API status code table defines it as an invalid or null value specified for a restricted picklist ^[1]. It is not new in Winter ’27: Salesforce Help articles on it carry May 2026 publication dates ^[2], and a vendor knowledge base entry on the same error dates to 2018 ^[3]. This report uses Salesforce Winter ’27 (API version 68.0) as the validation baseline ^[4], and records the Data Loader v67.0.0 download listed on 2026-10-27. No live customer org was tested.

The central finding is that "the value exists" is an incomplete diagnosis. A value can exist in the field's value set and still be rejected because the check runs against API names rather than labels ^[5], because the value is not selected for the record type being written, because a restricted dependent picklist has a default while its controlling field is missing from the page layout, or because stored records hold values that predate the restriction ^[6]. In the record type and historical cases a metadata comparison between orgs can show no difference ^[6].

The report offers one field-level diagnostic matrix with 16 columns, a test matrix per invocation path, and a four-way mismatch classification: payload-only, metadata-only, historical-data-only or unresolved. An AI assistant can collect accessible metadata and compare an exact failing payload with the allowed values, but a person decides whether a new business value should exist. Disabling the restriction is not a neutral repair: with the setting unchecked, Salesforce accepts any imported value and adds it as an invalid value ^[7], and re-enabling it makes later imports of undefined values fail.

Documented limits shape the repair. Restricted picklists cap at 1,000 combined active and inactive values ^[8], and Data Loader import batches cap at 200 records over SOAP and 10000 over the legacy Bulk API option (Bulk API 2.0 sets batch size automatically) ^[9]. Behavior also differs by surface: the Data Import Wizard ignores field dependencies, and the API does not enforce the value list for unrestricted picklists, according to the archived 264.0 documentation snapshot, which should be re-tested against API 68.0 ^[10]. Every claim here should therefore be re-tested per surface in a sandbox before a change is approved.

Introduction and Background

Salesforce administrators and consulting-partner support teams meet this error after imports, integration writes and configuration changes. The text is short but the cause sits in one of several layers. This report gives a repeatable order of work: capture one reproducible failure, check the input's identity, locate the configuration layer, test the invocation path, compare source and target, then choose the smallest approved correction.

The scope covers restricted picklists (and, for contrast, unrestricted ones) on standard and custom objects as handled by the UI, imports, bulk tools and API integrations. Salesforce Help, Trailhead and developer documentation are treated as platform documentation, vendor knowledge base entries as vendor-specific workflow advice, and everything else as hypothesis, each labeled as such.

Baseline and versions. Winter ’27 ships API version 68.0, with production waves on September 4, October 2 and October 9 ^[11]. No restricted-picklist validation change was identified in the Winter ’27 release notes at the time of writing, so nothing here is presented as a Winter ’27 behavior change. Record the API and client version in every test: the Data Loader download page lists v67.0.0 ^[12].

Evidence limits. No live customer org was tested. Where documentation is silent, such as whether a given integration enforces a UI dependency, the matrices say "test and record".

Publisher perspective. The publisher, cirra.ai, offers an MCP server for Salesforce administration that runs as the connected user. It appears here only as one optional interface for verified metadata reads and approved changes, beside Salesforce's own options; it is not a data deployment platform. The wider decision about where picklist values should vary is a question of record types, page layouts and dynamic forms.

How Restricted Picklists Work: Definitions and Taxonomy

A restricted picklist accepts only values an administrator has defined: Trailhead says restricted picklists keep users from adding new values, either through the API or other apps ^[13]. An unrestricted picklist differs outside the UI, because integrations and automation can still add new values via the API, automation, or other apps ^[13]. A Gearset article calls these "advisory" picklists, which accept any value as valid that is entered or selected ^[6].

Global value sets are always restricted and cannot be converted to unrestricted ^[14]. If a field uses one, "turn off the restriction" is not available, and a fix means editing the shared set, which changes every picklist that uses it.

The configuration layers

Table 1 separates the layers that can each produce the same error text.

Table 1 reads as a triage order. The first two rows answer "is this value defined at all". Active status and record type selection answer "is it offered here". The dependency and default rows answer "does it conflict with another field". Label handling comes last but is the cheapest to check and the most common payload error. The master picklist stays independent of record types and business processes, so a value removed from a record type is still in the master list. The Metadata API names the restriction flag on the value set, and a picklist that uses a global value set is restricted.

Three points are easy to miss. First, dependencies are created from the API names of individual picklist values, so renaming an API value after the dependency exists breaks it. Second, Salesforce's article on the Data Import Wizard error states that the values used must be API names and not the picklist value label. Third, the UI API returns both: label is for display and value is for the API, and the LWC adapter documentation adds that labels are translated for the running user.

Diagnosing One Reproducible Failure

Step 1: capture the failure

Start with a single failing operation. Record the org ID, object and field API names, the exact error text, the literal input as received, the record type, the user or client, and the operation. Keep the received label apart from the intended API value. For bulk-style API calls, per-record errors come back as an Error containing a status code, while request-wide errors come back as faults. In Data Loader, each run writes success and error CSV files ^[15], and the error file is the primary evidence.

Step 2: check the input's identity

Most failures are payload failures. Check in this order:

• API value versus label. With the restriction enabled, Data Loader validates the value against the defined API Name values in the field.
• Whitespace and case. Vendor knowledge bases list case mismatches among the causes ^[16], and Gearset states that two values differing only in letter case are different values to Salesforce ^[17]. Treat case and whitespace as significant until a sandbox test proves otherwise for your surface.
• Deactivated values still being sent. An integration can keep sending a value an admin has deactivated ^[16], and Apollo's knowledge base advises that values match exactly between both platforms ^[18].
• Country and state codes. With state and country picklists enabled, values must match the setup codes exactly.

Illustrative example (Hypothetical Example). Suppose a restricted custom field Region__c on Account has API values EMEA, APAC and AMER, with the label "Americas" on AMER. An import file holds Americas, amer, EMEA (trailing space) and EMEA. The first is a label, the second a case variant and the third a whitespace variant; only the fourth is unambiguously valid. Record all four literally in the diagnostic table, then test each in a sandbox rather than assuming which variants a surface tolerates. The field and values are invented.

Step 3: locate the configuration layer

The manual route is Setup: Object Manager, the field, then Record Types. Salesforce's article tells the admin to check whether the value is in the Selected Values column and, if not, to move it over from Available Values ^[5].

A read-only programmatic route exists in the UI API (the two resource descriptions cited below come from the archived 264.0 documentation snapshot, so re-test them against API 68.0). The single-field resource is GET /ui-api/object-info/{objectApiName}/picklist-values/{recordTypeId}/{fieldApiName} for Picklist and MultiPicklist fields ^[19], and a bulk variant returns every picklist of one record type, which is especially useful for dependent picklists ^[20]. Results are scoped to a record type, and the master record type ID is 012000000000000AAA ^[21].

GET /services/data/v68.0/ui-api/object-info/Account/picklist-values/012000000000000AAA/Region__c

That path is a template built from the documented resource and was not run against a live org. API calls need an API-enabled user; object support and further permissions for this resource were not verified, so confirm them in the target org.

A generic schema describe is not an equivalent of the UI allowed-value list. A Salesforce developer blog states that dynamic Apex does not handle values for specific record types ^[22]. The SOAP describeLayout() call is the documented alternative, because its record type mappings carry the acceptable values for the record type ^[23]. An empty controllerValues map is expected for an independent picklist, but it does not prove independence when the controlling field is protected by field-level security.

The diagnostic table

The reusable asset is one row per field and failure, kept as a CSV with these 16 columns:

object_api_name,field_api_name,received_label,received_api_value,active,value_set,record_type,controlling_value,default,source_org,target_org,invocation_path,observed_result,evidence_url_or_id,recommended_action,approval

• Identity columns: object_api_name and field_api_name hold exact API names; received_label and received_api_value keep what arrived apart from what was intended.
• Configuration columns: active, value_set (local or global), record_type, controlling_value and default.
• Comparison columns: source_org and target_org, with API versions.
• Evidence columns: invocation_path, observed_result and evidence_url_or_id (job ID or error file).
• Decision columns: recommended_action and approval, the named human approver.

An optional read-only prompt for an AI client asks for an evidence table and stops before any write:

Using only metadata the connected user is permitted to read, build an
evidence table for this failure. Inputs: object, field, record type ID,
literal received value and the exact error text. For the field, list the
value set (local or global), each value's API name, label and active status,
the record type's selected values and default, the controlling field and
mapping, and whether the restriction is enabled. State what you could not
read. Compare the literal received value to the allowed values character by
character. Do not create, edit or delete anything. Do not propose new
business values; list them as questions for the admin. Stop after the table.

The prompt does not make an assistant's answer authoritative. It produces a table a human can check against Setup.

Surface-by-Surface Behavior and the Dependent and Default Case

The dependent and default scenario

Salesforce Help documents one cause separately from imports: a restricted dependent picklist has a default value, but the controlling field is not on the page layout ^[2]. The conditions are listed together: the restriction is enabled, the field is dependent, the layout lacks the controlling and dependent fields, and a default is set at the record type or the field. The article adds that a Mass Quick Action with a Predefined Value Set and any active trigger on the object can produce the same error. The documented fix is to remove the default from the record type or the field, depending on where it is set ^[2].

This fix is specific. If the field is not dependent, or the layout does include the controlling field, removing defaults changes behavior without addressing the cause. The same article lists additional causes: deploying a picklist field from a sandbox when the values are not selected on the record types ^[2], and using the label rather than the API name in an update.

Test matrix by invocation path

Do not generalize that every API write enforces every UI dependency or record-type constraint the same way. Test each surface and label the result. Table 2 lists what the documentation states and what remains a test.

Table 2 is a plan for evidence, not a verdict on any surface. The first rows rest on Salesforce documentation, while the connector row rests on one vendor's knowledge base and describes only that vendor's integration. Run the matrix twice, once with a value meant to be valid and once with a deliberately invalid one, and keep each observed outcome beside its invocation path in the diagnostic table.

Comparing Source and Target, Schema and Stored Data

When a change works in a sandbox but fails elsewhere, compare metadata first and stored data second. A sandbox inherits metadata from production ^[27], so differences can appear whenever one org changes after the last sync.

Matching metadata is not proof that every stored value is currently valid. Gearset's documentation of this exact error explains that it can occur when a metadata comparison shows no difference, if some picklist values were added before the picklist was made restricted. In its worked example, a record created through the API while the picklist is unrestricted adds the value as inactive metadata; if the picklist is later made restricted, the record keeps the invalid value ^[6]. A second cause is that records deployed without their record type take the target's default record type, so the value may not be offered.

A mismatch classification

Classify every flagged row before choosing a fix:

• Payload-only: the input is wrong (label, case or whitespace variant, deactivated value still sent) and metadata in both orgs is correct.
• Metadata-only: the value is absent from the field's set, the record type selection, or the target deployment.
• Historical-data-only: metadata matches, but stored records hold values that predate the restriction or dependency.
• Unresolved: the evidence does not separate the cases; keep the row, with the open question named.

If you calculate a mismatch rate, define it as flagged input rows divided by examined rows and disclose the scope: object, file, time window and surface. It is a local quality-assurance calculation for one batch, not an industry benchmark.

Separate data repair from schema repair. Schema repair changes the value set, record type selection, dependency or default and goes through change control. Data repair changes stored records or incoming payloads and may need a different approver. Gearset's options for the historical case show the split: add the value to the restricted set in the target (schema), change the record to a value in the set (data), or exclude the record from the deployment ^[6].

Deployment tooling adds traps that resemble this error but are not it. A Metadata API deletion makes a picklist value inactive instead of removing it ^[28], standard picklist values live in a standard value set rather than on the field ^[28], and a record type that references a missing value fails validation with a different message ^[17]. Copado's documentation notes that Salesforce retrieves record type picklist assignments only when the record type and the picklist field are selected in the same deployment ^[29].

Choosing the Smallest Approved Correction

Choose in this order and stop at the first option that explains the evidence:

• Fix the mapping or payload. Adobe's and Marketo's knowledge bases advise checking Salesforce for the acceptable values and correcting the source record ^{[30] [3]}.
• Activate or select an intended value. If the business already approved the value, reactivate it or move it into the record type's Selected Values.
• Repair the tested dependency or default case. Only if the stated conditions hold, remove the default from the record type or field.
• Reject or quarantine obsolete input. Keep the restriction, reject the row and record the decision.

Why turning off the restriction is not the routine fix

Some vendor knowledge bases offer disabling the restriction as a workaround, for example HubSpot's guidance that turning it off lets any values sync ^[26], and Adobe's note that state and country picklists could be disabled if not needed ^[30]. These are vendor workflows for their own integrations. Salesforce's platform article describes the consequence: with the restriction disabled, Salesforce accepts any imported value, even one the administrator did not define, and adds it as an invalid value. Salesforce calls this expected behavior and recommends enabling the restriction so that an import of undefined values errors instead ^[7].

Unrestricting a field to clear an error converts a loud failure into silent drift. Undefined values accumulate, reports and dependencies see categories nobody approved, and a later re-restriction leaves those values stranded on records, which is the historical case above. It also cannot be done for a field that uses a global value set ^[14]. Treat it as a time-boxed, approved exception, never a default.

Where an AI assistant helps, and where it must stop

An assistant is useful for collection and comparison. Given an exact failing payload, it can read accessible metadata, compare the literal input with the allowed values, group failures into the four categories, and draft a minimal patch for review. It should also list unanswered questions: is the value a real business category, who owns the list, and should the source system or the picklist change.

It must not invent values, remove restrictions by default or reinterpret business categories silently. Whether a new business value should exist is a human decision. A connected tool acts only within the connected user's permissions; Salesforce states that for its hosted MCP servers, field-level security, object permissions and sharing rules apply to every tool call ^[31].

Table 3 compares routes for connecting an AI client to an org for this audit.

Table 3 shows that the routes differ mainly in where change control lives. The DX server works from a local project and CLI-authorized orgs, hosted servers work through per-user OAuth, and the publisher's server is another connected-user option. None removes the need for a sandbox, a reviewer and an approval record, and none can exceed the connected user's permissions. The publisher's row comes from the publisher and has not been independently verified; confirm supported metadata types before planning a change around them.

Before-and-After Sandbox Test and Verification

Run each proposed correction as a controlled experiment.

• Before: with current configuration, submit one intended-valid value and one deliberately invalid value through the same invocation path that failed. Capture the outcome, error text, API version and client version.
• Change: apply the single proposed metadata change in a sandbox. If it travels by deployment, remember that deploying a record type also requires deploying the fields it references ^[34].
• After: repeat both submissions. The valid value should now succeed and the invalid value should still fail. If the invalid value now succeeds, the restriction was weakened and the change should be rejected.
• Approve and deploy: record the approver in the approval column and deploy through the normal path.
• Verify the target: repeat the two submissions in the target org and re-read the metadata. The sandbox is isolated from production, and production records may still hold invalid values the sandbox never had.

Recovering failed rows from a bulk load is a separate workflow. Check the results of a failed load first, because some records may already have completed. That article covers the recovery, and this report does not repeat it.

Data Analysis and Evidence

This section collects the quantitative facts used above, each from Salesforce documentation unless labeled.

Platform limits that shape the repair.

• Restricted picklist size: a combined limit of 1,000 active and inactive values ^[8].
• Global value sets: an org can have up to 500 ^[8]. Salesforce Help also describes a restriction for a global value set applied to more than 13 different objects, under which values can be deactivated but not replaced or deleted; confirm this against the live Help article before relying on it ^[8].
• Dependencies: a controlling field can have up to 300 values ^[35].
• Data Loader: maximum import batch is 200 records over SOAP and 10000 over the legacy Bulk API option (with Bulk API 2.0 selected, batch size is set automatically) ^[9]. Test how batch size and the client's all-or-none setting affect the rows an error file reports before relying on either.

Versions and dates (as of October 2026). Winter ’27 maps to API version 68.0. The Salesforce Help articles used here are dated May 23, 2026 and May 26, 2026.

Discrepancies between sources. None was reconciled by a live test:

• The Data Import Wizard FAQ states that the wizards accept any value for a picklist, while Trailhead says a restricted picklist makes the wizard use the default or possibly fail ^[24]. Read the FAQ as describing unrestricted picklists.
• Trailhead states that defaults can be set for controlling fields but not dependent picklists ^[36], yet Salesforce's restricted dependent default case shows that defaults on dependent fields exist in practice.
• Salesforce's import articles give the fix as adding the missing value in Setup or updating the import file; choosing between them is the business decision this report assigns to a human.

Implications and Future Directions

For support teams, the practical implication is that error text cannot choose the fix. A one-row evidence table, with the invocation path and record type captured, usually separates payload, configuration and historical-data causes faster than generic troubleshooting pages, and doubles as an audit artifact. For partners, adding the "valid value and invalid value" sandbox test to every picklist change request turns a recurring support ticket into a pre-deployment check.

For picklist governance, several practices follow from the documentation. Prefer global value sets where one list serves several objects, remembering they are always restricted. Deactivate rather than delete when records hold the value: existing records keep a value that is set to Inactive ^[36]. Avoid changing API names after dependencies exist. Keep record type selections in the deployment package when moving between orgs ^[29].

For AI-assisted administration, the direction is toward connected-user tools that read metadata, compare it with a literal payload and prepare a reviewable change. Salesforce's own MCP documentation sets the expected control model, with permissions applied per user. The open questions are practical: which metadata types each tool can read and write in a given edition, how reliably an assistant separates intentional restrictions from accidental ones, and who signs off. Answer them by test in your own org rather than by vendor claims, including the publisher's.

Frequently Asked Questions (FAQs)

What does "bad value for restricted picklist field" mean?

It is the interface form of the INVALID_OR_NULL_FOR_RESTRICTED_PICKLIST status code, returned when an invalid or null value is specified for a restricted picklist. Causes include a label sent instead of an API value, a value not available for the record type, and the dependent-default case.

How to fix "bad value for restricted picklist field"?

Work in order: check the literal input against API values, the record type's selected values, the dependency and default conditions, then compare source and target. Apply the smallest approved change. Salesforce's own fix for the dependent-default case is removing the default, which applies only when the stated conditions hold.

What is the difference between restricted and unrestricted picklists?

Restricted picklists accept only admin-defined values, including through the API. Unrestricted ones accept any value entered or selected, and an imported undefined value is added as an invalid value.

Why is a picklist value not available for the record type?

Record types determine the picklist values users can access ^[37], so a value can be valid for one and not another. A value can be fine in the field yet fail for one record type, because it is not in that record type's Selected Values. Check them, and note that Opportunity Stage and similar fields follow business processes instead.

Why does Data Loader reject a value that exists?

With the restriction enabled, Data Loader returns an error for an invalid value in the CSV. A label, a case or whitespace variant, or an inactive value fails even though a label is visible in the UI.

How to audit picklist values against record types?

Use the diagnostic table with a read-only evidence step: UI API picklist values for each record type compared with the field's value set and the literal payload.

What are picklist value set best practices?

Trailhead's Picklist Administration module covers choosing, managing and sharing picklist values ^[38]. Use API names consistently, prefer global value sets for shared lists, deactivate instead of delete, avoid renaming API values under dependencies, keep restricted fields restricted, and test a valid and an invalid value after every change.

How does a Salesforce admin MCP server fit?

It can serve as a connected-user interface for the read-only evidence step and, after approval, a minimal metadata change. Salesforce's hosted servers apply the connected user's permissions, and any alternative should as well.

Conclusion

A restricted picklist error is a symptom with several possible causes: an input that is not an API value, a value not selected for the record type, a dependency or default conflict, a source and target difference, or stored data that predates the restriction. The matrix in this report relates the received value, label, active status, value set, record type, controlling value, default and observed client behavior so each cause can be separated by evidence. The documented platform behavior is consistent on the main point: restrictions are enforced against defined API values, and removing the restriction lets undefined values in.

The recommended practice is to capture one reproducible failure, classify it as payload-only, metadata-only, historical-data-only or unresolved, make the smallest approved correction, and prove it with a before-and-after test of one valid and one invalid value in a sandbox and then in the target org. AI tooling can assemble the comparison and draft the patch, while people decide whether a business value should exist. All guidance here rests on documentation read in October 2026 for Winter ’27 and API version 68.0, without a live org test; re-test each invocation path in your own environment before relying on it.