The most common Craft CMS mistake is jumping into development before you have a plan. Developers start configuring sections, entry types, and fields before they’ve thought through their content model – and they end up with duplicate fields, redundant entry types, and sections that could have been collapsed into one. The same thing happens with templates: without planning which components are reusable, you get unwieldy Twig files full of duplicated code. After that, the technical mistakes pile on – ignoring eager loading, skipping cache tags, leaving devMode on in production. But the root cause, in my experience training over 1,000 developers at CraftQuest, is almost always the same: not enough planning before implementation.
Craft CMS is flexible enough to let you build things the wrong way without giving you any immediate feedback. Nothing stops you from creating five entry types that should have been one, or nesting content blocks three levels deep. The problems don’t surface until the project is well underway – or worse, in production with real content volumes.
These mistakes compound. A bad content model forces complex template logic, which leads to performance hacks, which produces a site nobody wants to maintain. A reasonable baseline is under 50 queries per page and 250ms PHP response time (Fortrabbit). Most new Craft projects blow past both numbers, and it usually traces back to decisions made in the first week.
I talk about this in my short course, The Craft Mindset: before you configure anything in Craft, you need to do content modeling and planning. Before you can even do that, you have to understand how Craft works and stores content. Then you take whatever your source material is – the content a project actually needs – and slowly convert that into a content model.
A content model is just a plan. It can be a digital document or a paper document. What it does is force you to think through the different types of content in your project. You work through which fields you need – plain text, drop-down, light switch, Matrix – and you go through the content divided up into types to understand how all the types are related. Maybe different types of content can all fall under one type. Maybe you really need to break them out into several.
With that plan, you move into implementation: configuring sections, entry types, fields, and field layouts to accept that content.
When developers skip this step and implement on the fly, they start realizing they have duplicate fields, duplicate entry types, or even entire sections that could have been collapsed into a single section. They didn’t look at their content holistically before jumping into configuration. It’s obvious once you start working, but by then you’ve already built on a shaky foundation.
A useful constraint: limit content blocks to six types per field (Knut Melvaer). If you need more than six, you probably need to rethink the content structure, not add more options. And be careful with nesting – multi-site installations multiply query counts proportionally (Craft CMS official docs), so a content model that’s merely slow on one site becomes unusable on four.
In the same way you plan content, you need to take some time and plan before you implement any templates. Say you have a set of static templates that a designer created. Before you start converting them into Twig templates in Craft, look through them carefully. Think about which components are reused in other places on the site. Which ones are similar enough that, with some settings tweaks or passing in different parameter values, you could have one component serving multiple scenarios?
If you plan, it keeps you from having unwieldy templates with a lot of duplication and a lot of reused code. Without that planning step, you end up with templates that are hard to maintain and hard for anyone else to pick up.
Andrew Welch of nystudio107 has a useful guideline for knowing when your templates have gone off the rails:
“If more than half your template is Twig logic – conditionals, loops, data manipulation – you have too much business logic in your templates.”
– Andrew Welch, nystudio107
That logic belongs in a custom Craft module or Twig extension, where it can be tested and reused without digging through presentation markup. If you want to learn how to move logic out of your templates and into PHP code via a plugin or module, the Extending Craft CMS course on CraftQuest walks through exactly that.
The other template mistake that catches developers off guard is the N+1 query problem. Every related element – asset, category, entry – fetched inside a loop fires its own database query. A blog listing page that fetches a featured image for each of 20 entries runs 20+ separate queries without eager loading. With eager loading, it’s one.
You don’t notice this locally because your dataset is small and your database is on the same machine. In production, with real content and network latency, those extra queries add up fast. 53% of mobile visitors abandon sites that take more than 3 seconds to load (Google). N+1 queries are how you get there.
The fix is .with() in your element queries to eager-load related elements before you loop. The hard part is remembering to do it every time, because Craft won’t warn you when you forget.
Using {% cache %} without a defined cache key is one of the most common template mistakes in Craft CMS. Without explicit keys, Craft cannot efficiently invalidate cached content when entries change, leading to either stale pages or no caching at all.
A related anti-pattern: using {% spaceless %} on large template output as a performance workaround instead of implementing proper caching (Servd). Proper caching with explicit keys and sensible TTLs does the actual work. Your caching strategy should match your content update frequency – over-caching stale content is a mistake too, but no caching is almost always worse.
These are mostly beginner mistakes that experienced Craft CMS developers rarely hit, but they’re worth covering because they come up so often in early projects.
devMode left on in production is the most common deployment mistake. It disables template caching, outputs verbose error messages publicly, and forces asset cache-busting. If your production site has devMode enabled, fix that before anything else.
Hardcoded configuration is the next offender. Craft’s multi-environment config system – .env files combined with general.php – exists so you don’t have credentials and environment-specific settings baked into your config files. Use it.
Ignoring the queue runner catches people on any site with email notifications, search indexing, or image transforms. The default web-based queue runner works for development but causes timeouts in production. Set up a CLI daemon instead. Craft 5 has over 150 General Config settings (nystudio107), so some misconfiguration is expected – just know which settings matter for production.
I talk about all of this in both the Craft CMS Quick Start Guide course, which I make available for free to everyone, and in the premium course Real-World Craft CMS, where I step through what it’s like to actually create sites using this planning method.
The broad pattern I’ve observed: beginners over-complicate their content models, while experienced developers under-invest in caching and eager loading because they’ve always gotten away with it on smaller sites. Both groups are making the same fundamental error – assuming that what works at small scale will hold at production scale.
CraftQuest deliberately teaches content modeling before template development for this reason. Getting the model right prevents most downstream template mistakes. Craft’s flexibility is one of its greatest strengths, but flexibility without guardrails requires education.
If you’re starting a new Craft project, begin with content modeling. Sit down with the source content, map out your types and fields on paper, and only then start configuring Craft. Getting that right prevents the majority of the template and performance mistakes listed above.
If you’re auditing an existing project, enable the Debug Toolbar in your local environment and check the query count on your heaviest pages. Anything over 50 queries per page is worth investigating.
Ready to build the right habits from the start? Check out the Craft CMS Quick-Start Guide on CraftQuest, or if you’re brand new to Craft, start with the Getting Started Quest – a guided learning path that walks you through everything covered in this article and more.
Not planning before implementation. Developers jump into configuring sections and fields before they have a content model, which leads to duplicate fields, redundant entry types, and a structure that’s hard to maintain or scale.
Not using eager loading for related elements. This causes N+1 query problems that are invisible during development but cripple production sites with real content volumes. Use .with() in your element queries to load related entries, assets, and categories in a single query.
Check two things: nesting depth and block count. If you’re nesting entry types more than two levels deep, or your content blocks exceed six types per field, your model likely needs simplification. Use the Debug Toolbar to check your query count per page – anything over 50 queries is a red flag.
Use Twig for display logic only. If more than half your template code is conditionals, loops, and data manipulation, move that logic into a custom Craft module or Twig extension where it can be tested and reused.
Start with query count and work outward. Check queries per page using the Debug Toolbar (target under 50), implement eager loading for all related elements, use {% cache %} tags with explicit keys, ensure devMode is off, and run the queue via CLI instead of the web runner.