Few things damage trust in a Sitecore project faster than releases that break things. If every deployment comes with a nervous evening and a list of manual fixes afterwards, the problem is usually in a small number of predictable places.
Your best tool: showconfig.aspx
Sitecore builds its configuration by combining many files in the App_Config folder. What's in any single file doesn't tell you what Sitecore actually uses. The page /sitecore/admin/showconfig.aspx shows the final, combined configuration. When a setting doesn't behave as expected, check it here first, on the server where the problem happens.
In Sitecore 9 and later, showconfig.aspx can also show the configuration for a different role, which helps when you can't log in to a content delivery server.
1. Config patches load in the wrong order
Sitecore applies patch files in a specific order: by layer (defined in Layers.config), then by folder, then alphabetically. If two patch files change the same setting, the last one wins. A patch named Feature.Search.config may be overwritten by one named Project.Website.config without anyone noticing.
Fix: keep your own patches in the Include folder structure your solution agreed on, avoid two files changing the same setting, and check the final value in showconfig.aspx after each deployment.
2. A patch doesn't apply to the right server role
Sitecore 9 introduced role-based configuration. Patches can be limited with attributes like role:require="ContentManagement" or search:require="solr". That's powerful, but it means a setting that works on a single test server, which usually runs as "Standalone", may be ignored on separate production content delivery servers.
Fix: test on an environment that uses the same roles as production. Check the role:define setting in each server's web.config, and review role attributes on any patch that behaves differently between environments.
3. Environment settings mixed into code
Connection strings, host names, API keys and server-specific settings often end up in config files committed to source control. Then a deployment to production quietly brings in test values.
Fix: keep environment-specific values out of shared patch files. Use config transforms, environment variables, or your deployment tool's variable replacement. Sitecore also supports custom rule-based config attributes, such as an env:require attribute, which some teams use for this.
4. Serialization overwrites content
Tools such as Sitecore Content Serialization (SCS), Unicorn and TDS store Sitecore items in source control and push them during deployment. That's right for developer-owned items like templates, renderings and placeholder settings. It goes wrong when the serialized scope also includes content that editors change. The deployment then puts back the version from source control and editors' work disappears.
Fix:
- Only serialize items developers own, such as templates, renderings, layouts and settings.
- For items that need to exist once but then belong to editors, use the "create only" or "add only" option your tool provides.
- Review the serialization configuration whenever a new site or feature is added.
5. Assembly errors after deployment
Errors like "Could not load file or assembly" or a yellow error screen right after deployment often mean the build copied Sitecore's own DLLs, or another version of a shared library, into the bin folder. This happens when project references to Sitecore NuGet packages are set to copy locally.
Fix: reference Sitecore packages so they're not copied to the output, for example with PrivateAssets or by turning off "Copy Local". Your deployment package should contain only your own assemblies. If you need a different version of a shared library such as Newtonsoft.Json, check the binding redirects in web.config carefully.
6. Manual steps nobody wrote down
Many deployments depend on steps that live in one person's head: populate the Solr schema, rebuild an index, clear a cache, update a setting item, restart a service.
Fix: write a short release checklist and keep it in source control next to the code. Automate the steps that run every time. A checklist alone removes most "it worked last time" problems.
What to do next
Next time something works on test but not in production, compare showconfig.aspx on both servers before changing anything else. Most of the time the difference is right there. If your deployments are still painful, I can review your pipeline and configuration as part of a support engagement, or work under your brand through white-label development.
