You might hit this Salesforce validation error when deploying a Lightning console app (CustomApplication):
The
<TabName>tab in the workspace mapping is not defined. Include the<TabName>tab or remove the extra workspace mapping. (line###)
This error comes from Salesforce's metadata validator, not Gearset. It means the CustomApplication XML contains a workspace mapping that points to a tab the app itself doesn't declare.
What is a workspace mapping?
A Lightning console app is a CustomApplication with <isServiceCloudConsole>true</isServiceCloudConsole>. Unlike a standard Lightning app, a console app lets users open records as workspace tabs and related records as subtabs.
To control how that works, a console app has a <workspaceConfig> section containing one or more <mappings>. Each mapping tells Salesforce when this tab is opened inside the app, here's how it should behave.
How are tabs and mappings defined?
Tab declaration
Every tab available in the app is listed at the top level of the CustomApplication:
<tabs>standard-Account</tabs>
<tabs>standard-Contact</tabs>
<tabs>Invoice__c</tabs>
<tabs>Contract__c</tabs>
Workspace mapping
Inside <workspaceConfig>, each <mappings> block references one of those tabs:
<workspaceConfig>
<mappings>
<tab>Invoice__c</tab>
</mappings>
<mappings>
<fieldName>ContractId</fieldName>
<tab>Contract__c</tab>
</mappings>
<mappings>
<tab>Project__c</tab>
</mappings>
</workspaceConfig>
The <tab> value inside <mappings> must exactly match one of the app's top-level <tabs> entries.
Why you're seeing this error
Salesforce validates that every workspace mapping points to a tab the app actually includes. If a mapping references a tab that isn't in the app's tab list, validation fails with this error.
In the example the error was reported against:
Invoice__candContract__cappear in both<tabs>and<workspaceConfig><mappings>, so these are fine.Project__conly appears inside<workspaceConfig><mappings>. It's mapped, but never declared as a tab of the app. This is what Salesforce is complaining about.
How to fix it
From the error message, take the tab name (for example,
Project__c) and the line number.Open the CustomApplication XML and search for that tab name. You should see two kinds of results:
a top-level
<tabs>TabName</tabs>entry (the declaration), anda
<mappings><tab>TabName</tab></mappings>block inside<workspaceConfig>(the mapping).
Decide which one is correct for your app:
If the tab should be part of the app, add a top-level
<tabs>TabName</tabs>entry so the mapping has something to point at.If the tab shouldn't be part of the app, remove the
<mappings>block that references it.
Once every workspace mapping points to a declared tab, the deployment should validate successfully.
If you're unsure which option is right, compare the two orgs in Gearset. If the tab exists in source but not target, it's usually missing from your deployment package and you need to add it. If the mapping is a leftover from a tab that was removed, you can safely delete the mapping.
Useful resources
Salesforce Metadata API Guide: CustomApplication
Salesforce Help: Salesforce Console
Gearset blog: How to deploy a Lightning page in Salesforce
Disclaimer: This error is returned by Salesforce directly, rather than Gearset. Even so, we offer guidance based on our combined experience with the Metadata API. Where possible, we try to help guide you to fix or avoid this error. In the case that this isn't possible, we may need to direct you to Salesforce support for further clarification.