Determine whether an ancestor element has containment declared
A container query that refuses to fire is almost always measuring the wrong box. It's rarely failing outright. The body and html elements don't get containment by default, even though they wrap every other element on the page, so a container query with no explicit container-type declared on an ancestor just fails rather than falling back to the viewport the way a media query would. That's the gap behind a widely cited setup: an article grid inside a main element with containment only on main. The query silently measures the wrong box, and the fix means tracing the DOM down to find exactly which element needs its own containment context.
The containment context also has to sit at the right level in the DOM tree. Say you've got a main element wrapping several article children, and you set container-type: inline-size on main. Any @container rule targeting those articles will respond to the width of main, not the width of each individual article. If the articles sit in a CSS grid or flex row inside that container, they can run far narrower than 60ch while main itself stays wide, and the query won't trigger the way you'd expect just by looking at it. The fix: give each article its own containment context. That means nesting a container boundary one level deeper than most people assume on first attempt.
Three more technical gaps are worth tracking as the spec matures. First, container-relative units such as cqw and cqh depend on browser support that's rolled out unevenly, so relying on them in production without a fallback value can leave layout gaps in older engines. Second, style-based container queries, which let you query custom property values rather than just size, are still under active development across browser implementations. Treating them as stable today is premature. Third, an element can't query its own containment context. A container can't be the subject of its own query, which means the size-aware styling always has to live on a descendant, not on the container element itself.
Before writing a single @container rule, confirm which element actually holds container-type, then trace the DOM path from that element down to the one you're styling.
Fixing the specific layout failures developers keep hitting
Once containment lives on the right ancestor, the next step is recognizing the failure pattern that mistake produces in practice. The most common failure mode shows up exactly as described in widely cited walkthroughs of this feature: someone sets up an article grid inside a main container, expects the articles to shrink their padding and font size once they get narrow, and nothing happens. Why? Because main is the only element with containment defined, and its width never drops below the query threshold even as its children do. The same failure repeats with CSS grid layouts, where the grid container stays wide but individual grid items go narrow, and with flexbox, where flex children shrink below the query breakpoint while the flex parent sits comfortably wide the whole time. In every case, the query is technically working. It's just measuring the wrong box.
This matters because container queries solve problems media queries and flexible typography never handled well. Developers managing component libraries have long needed to change content hierarchy, repositioning an element higher or lower in a stack, or swapping flex-direction, based on the dimensions of the component itself rather than the browser window. A media query can't do this: a sidebar widget and a full-width hero block can occupy the same viewport width while needing completely different internal layouts. Typography has the same gap. Font size adjustments tied to viewport width look wrong the moment a component gets reused in a narrower column, because grid and flexbox give you no native way to resize text based on the space actually available to that component.
A frequently cited illustration is a media player component. At a small size, it should show only a play button. A bit larger, and it generally has room for the play button plus details like the brand name and song title. Much larger, and it can show a full playlist alongside the time and brand. None of those breakpoints map cleanly to viewport width, since the same player might show up in a narrow sidebar on a wide screen or fill most of a narrow mobile viewport. Before container queries, developers solved this with manually calculated breakpoints based on surrounding column widths and gaps, a technique that's fragile by design: adjust the gap or padding on a neighboring column and you shift the point where content overflows. Because the failure only shows up in a narrow range of viewport widths, it tends to slip past the developer and get caught by users instead.
When a container query feels like it isn't firing, check three things in order: whether container-type is declared on an actual ancestor, whether that ancestor is the element you meant to measure, and whether the queried element itself is also trying to serve as its own containment context.
Weighing how much container query logic to adopt right now
With the common failure modes and fixes out of the way, the remaining question is how far to take this across an existing codebase. For most teams, the practical decision is whether to replace existing viewport-based utility class systems with container-based ones, and the honest answer depends on how many of these pitfalls your component library already works around manually. Teams that built padding and font-size utility classes tied to viewport breakpoints can now tie those same utilities to a contained size instead, producing layout decisions proportional to the actual component rather than the window. That's a direct improvement over the calculated-column-width technique, where someone manually computes breakpoints based on surrounding gap and padding values, a method that works fine until a different developer adjusts the gap on an unrelated column months later and content starts overflowing at a viewport width nobody's testing.
Browser support for the core container-type and @container features is broad enough for production use in most modern codebases. The two edges of the spec still deserve caution before you commit to them, though. Container-relative units like cqw give you fluid sizing tied to the container rather than the viewport, but check fallback behavior against whatever browser versions your analytics actually show traffic from. Style-based queries that check custom property values rather than dimensions are still being finalized across engines, so building critical layout logic on top of them today means you'll be revisiting that code as the spec and implementations keep settling.
The next decision point is straightforward: audit any component that currently relies on viewport media queries for internal layout changes, and check whether it ever gets reused in a context narrower or wider than the full viewport. If so, that component is a direct candidate for a containment context and an @container rule instead of another breakpoint. That audit, not a wholesale rewrite, is what resolves the original problem: a query measuring the wrong box is a tracing error, and tracing the DOM to the correct ancestor fixes every case described above.