Why Does Salesforce CLI Warn About GlobalValueSets Not Found Locally?

When deploying metadata using the Salesforce CLI, you might encounter warnings like these, even though the deployment completes successfully:

Warning: GlobalValueSet, Value_Set_One__gvs, returned from org, but not found in the local project
Warning: GlobalValueSet, Status_Type__gvs, returned from org, but not found in the local project
Warning: GlobalValueSet, Confidentiality_Level__gvs, returned from org, but not found in the local project

Warning: GlobalValueSet, Value_Set_One__gvs, returned from org, but not found in the local project
Warning: GlobalValueSet, Status_Type__gvs, returned from org, but not found in the local project
Warning: GlobalValueSet, Confidentiality_Level__gvs, returned from org, but not found in the local project

This situation can be confusing because the Global Value Sets (GVS) clearly exist in your local project under:

force-app/main/default/globalValueSets/*.globalValueSet-meta.xml

force-app/main/default/globalValueSets/*.globalValueSet-meta.xml

Why Does This Happen?

This behavior is caused by a change introduced in Salesforce API version 57.0 and later. Salesforce now automatically appends the __gvs suffix to the developer names of all Global Value Sets when retrieved from an org. This means that even if your local file is named Value_Set_One.globalValueSet-meta.xml, Salesforce internally treats it as Value_Set_One__gvs.

As a result, when the CLI compares your local project with the org, it sees a mismatch between Value_Set_One__gvs in the org and Value_Set_One locally, triggering the warning.

Workarounds and Solutions

1. Adjust API Version

One workaround is to use an older API version that does not automatically append __gvs. You can configure your sfdx-project.json to use API version 56.0 and deploy using the command-line switch:

sfdx force:source:deploy --api-version 56.0 -p force-app/main/default

sfdx force:source:deploy --api-version 56.0 -p force-app/main/default

This avoids the warnings because the API does not append the __gvs suffix.

2. Rename Global Value Set Files Locally

If you want to work with API 57.0 or later, you can rename your local GVS files to include the __gvs suffix:

Value_Set_One.globalValueSet-meta.xml  →  Value_Set_One__gvs.globalValueSet-meta.xml

Value_Set_One.globalValueSet-meta.xml  →  Value_Set_One__gvs.globalValueSet-meta.xml

Additionally, ensure that the <fullName> tag inside the XML also includes the __gvs suffix:

<?xml version="1.0" encoding="UTF-8"?>
<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Value_Set_One__gvs</fullName>
    <customValue>
        <fullName>one</fullName>
        <default>false</default>
        <label>One</label>
        <isActive>true</isActive>
    </customValue>
</GlobalValueSet>

<?xml version="1.0" encoding="UTF-8"?>
<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <fullName>Value_Set_One__gvs</fullName>
    <customValue>
        <fullName>one</fullName>
        <default>false</default>
        <label>One</label>
        <isActive>true</isActive>
    </customValue>
</GlobalValueSet>

After this change, deploying the metadata works without warnings.

3. Use --ignore-conflicts to Update Source Tracking

Even after renaming the files, you may notice that retrieving the GVS from the org still returns the old name without __gvs. This appears to be a bug in the CLI:

sf project retrieve start --metadata GlobalValueSet:Value_Set_One__gvs

sf project retrieve start --metadata GlobalValueSet:Value_Set_One__gvs

May still return:

Retrieved Source
| State  | Name           | Type           | Path
| Created| Value_Set_One  | GlobalValueSet | force-app/main/default/globalValueSets/Value_Set_One.globalValueSet-meta.xml

Retrieved Source
| State  | Name           | Type           | Path
| Created| Value_Set_One  | GlobalValueSet | force-app/main/default/globalValueSets/Value_Set_One.globalValueSet-meta.xml

To work around this, after creating a scratch org, deploy with the --ignore-conflicts flag. This updates the local source tracking to match the org:

sf project deploy start --ignore-conflicts

sf project deploy start --ignore-conflicts

This updates the .sf/orgs/<org-id>/maxRevision.json file, aligning the Global Value Set state between local and remote.

Summary

These warnings are a result of Salesforce API changes in version 57.0+, which append __gvs to Global Value Sets. You can handle them by either using an older API version, renaming local files to include __gvs, or updating source tracking using --ignore-conflicts. While the deployment itself usually succeeds, addressing these warnings ensures your local project stays consistent with the org and prevents confusion when retrieving or deploying metadata in the future.

Job-Oriented Salesforce Training with 100% Money Back Assurance

Our Salesforce Course is structured to provide a comprehensive understanding of the Salesforce platform, equipping you with the essential skills needed to excel in the CRM industry. The program covers important modules like Salesforce Admin, Developer, and AI, seamlessly integrating theoretical concepts with hands-on application. Through practical assignments and real-world projects, you will develop the expertise to solve complex business challenges using Salesforce solutions. Our experienced instructors ensure that you gain both technical proficiency and industry-relevant insights to succeed in the Salesforce ecosystem.

Beyond technical expertise, our Salesforce training in Hyderabad includes personalized mentoring, certification preparation, and interview coaching to enhance your career opportunities. You’ll have access to extensive study materials, live project exposure, and dedicated support throughout your learning journey. By the end of the course, you will be fully prepared for certification exams and possess the real-world skills that employers seek. Start your Salesforce career with us and explore limitless career possibilities. Sign up for a Free Demo today!