The rest of this post was written with Claude AI. Here's the simple problem I seem to get myself into often:
I have views that need a strongly typed model, but modelsbuilder hasn't put the models on disk so Umbraco completely fails to start. dotnet run just fails 😱 But I need to get into the backoffice to generate the models; difficult when Umbraco doesn't even run.
After I encountered this today, I finally took some time to figure out what the easiest way is to get this fixed. What follows is the summary of what Claude did for me:
Dropped a set of strongly-typed views (home.cshtml, Author.cshtml, etc.) into a fresh Umbraco site and ran straight into the chicken-and-egg problem every Umbraco developer eventually meets:
- The views reference
Umbraco.Cms.Web.Common.PublishedModels.Home(and friends). - Those classes are generated by ModelsBuilder from document types that live in the database.
- The database is empty until the site has run at least once.
- The site won't build because the views don't compile, so it can't run.
Here's the little dance to break the cycle.
1. Turn off Razor compile-on-build
In the .csproj:
<RazorCompileOnBuild>false</RazorCompileOnBuild>
The build now skips the views entirely instead of failing on the missing PublishedModels.* types.
2. Switch ModelsBuilder to manual mode
In appsettings.json:
"ModelsBuilder": {
"ModelsMode": "SourceCodeManual"
}
SourceCodeManual is the only mode that gives you a Generate models button in the backoffice. The other three:
| Mode | Files? | Trigger |
|---|---|---|
Nothing |
none | — |
InMemoryAuto |
in-memory only | auto |
SourceCodeManual |
~/umbraco/models/*.cs |
button |
SourceCodeAuto |
~/umbraco/models/*.cs |
auto on schema change |
3. Start the site
dotnet run. The build succeeds (views aren't compiled), the app starts, and the backoffice comes up. Frontend pages will 404 or 500 right now — that's expected and we don't care yet.
4. Click the button
Backoffice → Settings → Models Builder → Generate models.
.cs files appear in umbraco/models/ — one per document type. These are the classes the views were waiting on.
5. Stop the site
Ctrl+C.
6. Re-enable Razor compile-on-build
Remove the line we added in step 1:
<!-- <RazorCompileOnBuild>false</RazorCompileOnBuild> ← delete this -->
7. Start the site again
dotnet run. Build picks up the generated models, compiles the views against them, the home page renders.
Why the dance is needed
RazorCompileOnBuild=false alone isn't a real fix — it just moves the compile error from build time to the moment a frontend page is hit. Without runtime compilation registered, Umbraco's view-engine lookup returns "no physical template file found" and serves a 404. You'll see this in the logs:
"No physical template file was found for template home"
The actual fix is to get the models on disk. The flag just buys you the brief window between "build doesn't run" and "models exist" so you can boot the backoffice and press the button.
Once the models are committed to source control, none of this matters — the next clone builds clean from the start.
Top comments (3)
@mistyn8 Yeah, it's just that the Views were being compiled, and they needed models to exist otherwise they can't compile. So just changing the models mode would never work as there were just build errors.
Unless it changed, SourceCodeAuto does provide a button to manually force an update of the models as far as I know. We're always working with SourceCodeAuti and I sometimes regenerate the models manually.
Nevertheless, good post!