Why Doesn’t My Visual Studio Solution Build? A Troubleshooting Guide

broken building

I’m pretty good at getting Visual Studio projects building correctly – I’m a bit of a Visual Studio whisperer. In one job I could get the ‘flag ship’ application up and running on a new machine in half the time of anyone else – that still meant half a day’s work. Strangely that’s not on my CV.

So here are the steps I go through to get a rogue project building in Visual Studio. These steps range from the basic to the bizarre. They are in the order I would do them and by following them I can pretty much get any Visual Studio project back on track. So put on your tin hat and let’s get that errant Visual Studio solution building.

Sanity Check

Before embarking on a full blown Visual Studio troubleshooting endeavour it’s best just to do a few simple checks.

Have you got latest code?

Everybody has wasted hours trying to get an old version of the code working. I still do it. The developer that sits opposite me still does it. My boss still does it. Don’t do it. Get the latest version of the code from your repository.

Does it build for other people in your team?

Just see if other people are having the same problem. If you have continuous build – check that is still working and running through cleanly. The code might not work for anyone. More illuminating – it might work for some at not others.

Basics

Every few weeks you will probably be faced with a non-building Visual Studio project. Here are some basic steps to help. These will probably be enough.

Clean and rebuild

clean solution

Go to

Solution Explorer -> Right Click -> Select Clean -> Wait -> Select rebuild

Often the bin directories have gone all wonky and are full of junk. Who knows what has happen to them. Clean and rebuild will refresh them and often work when a normal build doesn’t. Standard stuff – but then we are just beginning.

Build each project individually

Often you are faced with mountains of errors which is misleading. It could be one of your low level library projects that is failing to build and causing all other projects to fail. Rebuild each project individually starting with the low level ones that are dependencies for others. Sometimes that’s enough to get the entire solution building. At a minimum, you will better be able to see where the actual issue is and not be swamped by a heap of irrelevant error messages.

Close and reopen Visual Studio

It’s time to restart your Visual Studio. Don’t leave this till the end – it is often the problem. Turn it on and off again – it might help.

As a note – in my experience restarting your computer rarely helps. By all means try it but don’t be surprised when the solution still stubbornly refuses to build.

Manually delete all bin folders

This is really worth a try if you are working with an application with language variants. The language specific resource (e.g. Messages.fr-CH.resx) files compile down into satellite resource files in your bin folder that are contain in their own subfolder e.g.

Weirdly Visual Studio Clean can leave these satellite assemblies behind. Your application will still build but it can cause changes in languages variants not to shine through.

This might seem like an edge case but this exact thing kept a colleague of mine baffled for 6 hours. It was a very emotional moment when we finally sorted it out. So this is very much worth a try.

Start Visual Studio in admin mode

run as administrator

I’m master of my own machine (i.e. I’m a local admin) and I’ve got my Visual Studio set to always open as an administrator. You might not. Right click and run as administrator.

If it isn’t possible get someone who is an administrator to open Visual Studio on your behalf. Then complain bitterly about not being a local admin or your own machine – you are a developer; you really should be.

Have you got bad references?

bad references

Just check all projects and make sure that the references are all there. Look out for the little yellow triangle. If you have bad references then jump to section below dealing with that.

Check IIS

This isn’t relevant for all projects but if you are building a web project using IIS then it’s worth doing checks around that. Obviously it’s a completely legitimate setup to use IIS Express. In that case this isn’t relevant.

IIS pointing at the wrong folder

This is often a problem when changing branches. Visual Studio normally makes a good job of switching for you but not always. If you are hooked up to the wrong folder then your project will build but you won’t be able to debug it. Also changes that you are convinced you are made won’t shine through. This has driven me crazy before.

IIS explore folder

To check

  1. Open IIS (run -> inetmgr)
  2. Navigate to website
  3. Press explore and confirm you are where you think you should be. You might not be in Kanas anymore.

Permissions on app pool

This won’t manifest itself as a build failure but the project won’t be running as expected particularly when accessing external resources. It might be worth checking what the app pool is running as.

 

application pool settings

To check

  1. Open IIS (run -> inetmgr)
  2. Application Pool -> select the one for the website
  3. Advanced settings

You can now check the user.

The application pool runs under ApplicationPoolIdentity by default. What I’ve sometimes seen is that it’s been changed to a normal user whose password has expired. This is typically fallout from previous Visual Studio failures echoing through the ages.

Bad references

bad references

If you are noticing a yellow triangle on your project references then Visual Studio can’t find a dependency. Sometimes there is no yellow triangle and all looks fine but it still can’t find the dependencies.

With the advent of nuget this is less of a problem now but it does still happen. There are instances where incorrect use of nuget makes it worse and more baffling.

Check reference properties

Go to the references -> right click -> properties

references properties

There are two things to look for

  1. Is it pointing to where you think it should be? It might not be
  2. Copy Local. Bit of witchcraft but I always set this to copy local. It will copy the dll into the bin folder so at least I can satisfy myself that it has found it and is copying it through OK.

Have you checked in the packages folder – don’t!

Even if you are using nuget your bad reference problem might not be at an end. Checking in the packages folder can cause the references not to be found. This is especially baffling since looking at the reference properties reveals no problems. The path to the required dlls is definitely valid and the dlls are definitely there. But it cannot be found – frustration and finger biting.

To resolve delete the packages folder then remove the folder from source control. Rebuild and all will be well.

Resetting Visual Studio

Resetting Visual Studio can (probably will) cause your environment to lose all your custom defaults – so all your shortcuts, settings perhaps plugins will go. Therefore I’ve left this step towards the end as it is not without consequences. That said it is often the resolution so it’s not a bad idea to do it earlier in the ‘what on earth is going wrong with Visual Studio’ resolution process.

Delete all temporary and cache files

This was a fix that often worked in slightly older versions of Visual Studio. I’m using VS 2015 currently and this often isn’t a problem. Still it is worth clearing out these folders and rebuilding

Delete project setting files

Your user settings for a project are stored in files with the extension *.csproj.user i.e

It’s worth deleting all those and rebuilding so reset user specific settings. Also if you have these checked into source control then remove them. They are specific to you and shouldn’t be in a shared repository.

Reset Visual Studio on the command line

When Visual Studio appears utterly broken and you are reaching for the uninstall button, this can often help. It takes Visual Studio back to its initial settings you will need to reapply any custom settings that you have.

Close VS then in a command prompt go to the folder that has the Visual Studio.exe (devenv.exe) i.e.

For VS 2015 it is

Then

Reopen visual studio

A similar approach can be used with devenv.exe /Resettings as detailed here.

Reset Visual Studio through file explorer

If the command line doesn’t work then try resetting Visual Studio via the file system. This often works when the command line doesn’t. Try this when Visual Studio is undergoing a profound collapse particularly when it keeps popping up an alert box detailing errors being written here…

i.e. for Visual Studio 2013

To resolve for Visual Studio 2013

  1. Close VS
  2. Go to C:\Users\tbrown\AppData\Local\Microsoft\VisualStudio\12.0
  3. Rename the folder to C:\Users\tbrown\AppData\Local\Microsoft\VisualStudio\12.0.backup
  4. Reopen VS. The folder C:\Users\tbrown\AppData\Local\Microsoft\VisualStudio\12.0 will be regenerated.

The process is the same for other versions of Visual Studio except the version number at the end will be different i.e C:\Users\tbrown\AppData\Local\Microsoft\VisualStudio\14.0 for VS 2015.

Disable plugins

Leave this one till last because it’s a pain. Go to Tools -> Extensions and plugins. Then disable each plugin you can one by one.

disable plugin box

It’s a pain because even if it is a plugin that causes it, you have a choice of uninstalling and living without it or contacting the vendor. Clearly if you didn’t buy it then the vendor isn’t going to be interested in helping you. I’ve found PostSharp and Resharper the likely culprits here. The Resharper vendor was very helpful. PostSharp weren’t (because we hadn’t bought it!!).

Bizarre Ones

Be careful what you check in

Checking files into source control that you really shouldn’t can cause difficult to diagnose problems. This often happens to me for continuous builds where the user building has fewer privileges than I’m used to. It does happen locally too. The following files shouldn’t be checked in

  • Bin folders
  • Obj folders
  • Autogenerated xml (i.e. documentation generated during build)
  • Packages folder
  • .csproj.user files

If you have checked them in then delete from your disk, remove from source control and rebuild.

Is your file path too long

Windows limits the file path to 260 characters. It could be that you have exceeded this and Visual Studio has started to complain. The awkward thing is that it complains in a very oblique way. The error that you see will be something on the lines of…

“obj\Debug\LongFileName.cs” has an invalid name. The item metadata “%(FullPath)” cannot be applied to the path “obj\Debug\LongFileName.cs “. obj\Debug\\LongFileName.cs           ContainingProject.proj            C:\Program Files (x86)\MSBuild\14.0\bin\Microsoft.Common.CurrentVersion.targets

So not obvious. Double click the error and it will take you to the Microsoft.Common.CurrentVersions.targets file in the depths of the framework folder. Less than illuminating.

Once you have diagnosed this then the resolution is easy – move your project to a shorter file path. I’ve found this a problem when switching branches which can have longer file paths than the Main branch.

If all else fails

If all else fails uninstall Visual Studio and reinstall. But honestly, I have reached this frustrating point, uninstalled, reinstalled, waited hours and the problem persists. This might not be the cure that you were looking for. Go into a corner and have a good long think before you resort to this one.

So congrats if you have read this far (or commiserations as your Visual Studio install is clearly in a bad way) but hopefully this guide will enable you to have a healthy and happy Visual Studio for years to come.

Useful Links

http://stackoverflow.com/q/1880321/83178
Good stack overflow explanation on why the 260 character filepath limit exists in windows.

https://msdn.microsoft.com/en-us/library/ayds71se.aspx
Official advice from Microsoft about bad references.

http://stackoverflow.com/questions/1247457/difference-between-rebuild-and-clean-build-in-visual-studio
There is a difference between Clean + Build and ReBuild as detailed here.

Leave a Reply

Your email address will not be published. Required fields are marked *