Terminal
Terminal/Skill
Reviews Umbraco code for common performance traps and anti-patterns, such as static references, slow tree queries and N+1 lookups, with fixes.
By Umbraco
Works with
npx skills add umbraco/umbraco-cms-implementation-skills --skill umbraco-common-pitfallsAn index of the most impactful mistakes in Umbraco development — issues that cause memory leaks, instability, N+1 queries, and poor performance. Source of truth: the official Umbraco docs.
The docs explain each pitfall. This skill adds what the docs don't: how to spot it in real code (Look for), what it looks like from the outside (Symptoms), and which pitfalls travel together (Related). Each reference file keeps a short summary and example, and names its section in the docs page (Docs section).
DescendantsOrSelf() and repeated Model.Root() calls), so check the Related links at the
end of each file.| Pitfall | Look for | Reference |
|---|---|---|
| Singletons and statics | static service fields, Service Locator calls | singletons-and-statics.md |
| Static references to request-scoped instances | static UmbracoHelper, static UmbracoContext | static-request-scoped-instances.md |
| Pitfall | Look for | Reference |
|---|---|---|
DescendantsOrSelf() on large trees | .DescendantsOrSelf() + .Where(x => x.Level == n) | descendantsorself-large-trees.md |
| Over-querying (repeated traversals) | Model.Root() / .Ancestor() called repeatedly | over-querying.md |
| Services layer in Razor views | @inject IContentService (or other I*Service) in .cshtml | services-in-razor-views.md |
| Not caching expensive lookups | Traversal to find a site-wide settings or nav node | missing-lookup-cache.md |
| Pitfall | Look for | Reference |
|---|---|---|
| Volatile data stored as content nodes | IContentService.Save() per request, submission, or import row | volatile-data-as-content.md |
| Pitfall | Look for | Reference |
|---|---|---|
| Expensive processing during startup | Heavy work in UmbracoApplicationStartingNotification | expensive-startup-processing.md |
| Rebuilding Examine indexes unnecessarily | Scheduled or code-triggered index rebuilds | unnecessary-examine-rebuilds.md |
| Service lookups inside Examine events | Service calls in TransformingIndexValues / DocumentWriting | service-lookups-in-examine-events.md |
| Pitfall | Look for | Reference |
|---|---|---|
RenderTemplateAsync for content rendering | RenderTemplateAsync used for on-page output | rendertemplateasync-misuse.md |
| Pitfall | Look for | Reference |
|---|---|---|
| Logic in constructors | Traversal or LINQ inside a model constructor | logic-in-constructors.md |
| Eager loading | Property values assigned in the constructor; resolved content stored on models | eager-loading.md |
| Memory pressure from object allocation | .Select(x => new Model(x)) over large collections | memory-pressure-allocations.md |
| Models Builder misuse | ModelsBuilder partials that traverse content or build view models | models-builder-misuse.md |
The official docs page covering these pitfalls targets Umbraco 17 and 18 — the only versions for which it is currently published. The underlying patterns apply to any DI-era Umbraco (v9+), but the documentation source is only verified against 17/18.
The C# APIs used in the reference examples were compiled against Umbraco.Cms 17.5.3 and 18.2.0
(checked 23-09-2026). Razor snippets were checked through their C# equivalents. On both versions
they compile with no obsolete-API (CS0618) warnings, with one difference: the
PublishedContentWrapped constructor, which is noted in
logic-in-constructors.md.
Currently active supported versions (as of 2026-08-05):
| Version | Type | End-of-Life |
|---|---|---|
| Umbraco 18 | STS | 25-06-2027 |
| Umbraco 17 | LTS | 27-11-2028 |
| Umbraco 13 | LTS | 14-12-2026 |
Versions 10–12 and 14–16 are end-of-life. Umbraco 13 remains supported until 14-12-2026. Source: Umbraco LTS & End-of-Life.
Objective assertions live in evals/evals.json; run them with
umbraco-skill-evaluator.