Fixing the “circular file references are not allowed” Error in ASP.net

If you get the “circular file references are not allowed” error in an ASP.net Website Project and you do not have any controls that have any obvious circular references, what does the error mean and how do you fix it?

See this blog post from Siderite Zackwehdex as well as this MSDN forum post: by default, in a Website Project, ASP.net compiles one dll per folder in an ASP.net project. So if you have the following setup:

/folder1/Control1.ascx > References Control2
/folder2/Control2.ascx > References Control3
/folder1/Control3.ascx

This means that the folder1 dll will reference the folder2 dll which will again reference the folder1 dll, causing a “circular file reference”.

Even if there is not a direct path between the controls, looping into a circular reference, but there is a direct path connecting the circular reference through other controls in the same directories, it can throw the circular file references error. For example:

/folder1/Control1.ascx > References /folder2/Control2a.ascx
/folder2/Control2b.ascx > References /folder1/Control3.ascx
/folder1/Control3.ascx

Ways to fix it:

  1. Rearrange the layout of your controls (or masterpages) to remove the circular references (normally this will mean moving one control to another folder – in the example above, move control2 to folder1). This is the preferred solution.
  2. Use batch=”false” in the compilation tag of the web.config file. This will cause a new dll to be created for each control/page in the site. This should fix the error but is really lousy for performance, so it should be avoided (especially on production sites).

(This has happened to me a couple of times already, so posting it here as a reminder to myself for the next time).