
Editorial illustration; the screens are representative, not a real Drupal interface.
A stylesheet can exist in your theme directory and still never reach the page. In Drupal, that is often a connection problem: the library name is wrong, the YAML definition points to a different path, or the right library was never attached to the render element that needs it.
This guide is for developers working on a Drupal theme or custom module. It follows one asset from file to browser and gives you a low-risk way to distinguish a bad path from an attachment, cache or JavaScript dependency issue.
Summary
- Drupal loads CSS and JavaScript through named asset libraries; having a file in the theme is not enough.
- Verify the filename, library definition, namespace and attachment point in that order.
- Attach assets to the component that needs them when possible, rather than every page.
- Clear the relevant cache only after confirming the source is valid, then check the rendered page and browser network request.
How the asset path works
Drupal’s official theming guide describes a three-part process: place the asset, define a library in a *.libraries.yml file, then attach that library to pages or render output. A theme library might look like this:
# mytheme.libraries.yml
product-card:
css:
theme:
css/components/product-card.css: {}
js:
js/product-card.js: {}
The file paths are relative to the extension’s root, and the library reference includes the extension name: mytheme/product-card. A declaration in mytheme.libraries.yml does not mean Drupal automatically adds it to every page.
The Drupal guide to adding theme assets describes the available attachment options and dependencies. The exact API used depends on whether the asset belongs to a theme, a component template, a block or a module.
1. Confirm the physical file and extension name
Start with the filesystem. Check the exact case and spelling of css/components/product-card.css and confirm the file is inside the theme directory Drupal is actually using. Case differences may be hidden on a developer’s laptop but fail on a case-sensitive server.
Next, confirm the machine name. The prefix in mytheme/product-card must match the theme or module directory and the name used by Drupal, not the human-readable label shown in the admin UI. If the library is supplied by a module, its namespace is that module’s machine name.
A simple but common mistake is declaring a path relative to the Drupal root while the library expects a path relative to the extension root. Compare the declaration with a known working file in the same extension.
2. Validate the YAML shape and library key
YAML indentation matters. Keep the css, js and dependencies keys at the correct nesting level. The library key (product-card above) is the part after the slash in the attachment reference.
If another library depends on this one, use the namespace form, such as mytheme/product-card. For a core dependency such as jQuery, declare the relevant core library when your script needs it; do not assume every page loads the dependency automatically. The Drupal asset system allows dependencies between libraries so loading order can be expressed directly.
After editing YAML, look for parser errors in Drupal’s logs or command output before investigating browser behavior. A missing or malformed library definition cannot be fixed by changing CSS selectors.
3. Find the attachment point
For a theme-wide stylesheet, a library can be listed in the theme’s .info.yml file. This is appropriate for genuinely global styles such as base typography or site layout.
For a component-specific asset, attach it closer to the output that needs it. A Twig template can use:
{{ attach_library('mytheme/product-card') }}
A render array can carry it as metadata:
$build['#attached']['library'][] = 'mytheme/product-card';
The Drupal module asset guide shows attachment through render arrays and hooks. Prefer the component or render array that owns the markup. Attaching a one-off script to every page may make the symptom disappear, but it adds cost to pages that do not use that feature and hides where the dependency belongs.
When attachment is conditional, ensure the condition follows the rendered component or includes the appropriate cacheability metadata. Otherwise cached output may not vary when the condition changes. Use the documented API appropriate to your Drupal version and extension.
4. Check what the browser received
Open the page with aggregation temporarily disabled only in a development or staging environment, if your workflow permits it. If the page seems stale after the asset request succeeds, follow Drupal cache troubleshooting before changing attachment logic. Inspect the rendered HTML for the expected CSS or script URL, then inspect the browser’s Network panel for the request status.
These observations separate several cases:
- No asset URL in the page: the library was not attached or did not resolve.
- URL appears but returns 404: check the file path and deployment contents.
- Request succeeds but style does not apply: inspect selector specificity, CSS syntax and whether another style overrides it.
- JavaScript loads but behavior fails: inspect the console and declared dependencies, then verify that the script runs after its required markup exists.
Do not infer a missing library solely from a visual result. A CSS rule may be loaded but overridden, and a script may be loaded but fail at runtime.
5. Clear caches after checking the source
Drupal caches extension discovery and rendered output. After changing a library definition or theme attachment, clear caches using the team’s normal development workflow, such as Drush cache rebuild where installed. On a shared production site, follow the release and change-control process rather than clearing caches casually.
If the file changed but its library definition includes a fixed version, review the current Drupal guidance on versioning and cache invalidation. Drupal.org notes that version information can affect aggregate-file hashes; an incorrectly managed version can leave browser or edge caches serving stale assets. If no version is specified, Drupal uses the asset contents under the documented behavior. Follow the current guide for the Drupal release in use.
Test again with a clean browser cache or a fresh session after the rebuild. Avoid repeatedly appending arbitrary query strings to URLs; that can conceal the actual cache configuration problem.
6. Test the narrowest affected page and one unaffected page
Check the component page where the asset should appear and another page where it should not, if the library is conditional. This catches both omission and accidental site-wide loading. Test a logged-out view too if the problem appears only for anonymous visitors; render caching can make those paths differ.
If production aggregation is enabled, test that configuration on staging before release. A development page that works with unaggregated assets does not prove the production aggregate will be correct. Record the URL, browser result, response code and relevant Drupal log entry for a teammate. For a repeatable way to test risky changes, see Drupal core updates with Composer.
Example: style works on one content type only
Suppose the card style appears on article pages but not on a landing page reusing the same Twig component. Compare how each page builds and renders the component. If one path attaches the library in a preprocess function and the other renders a different template, the library may not be attached consistently. Moving attachment to the component template or render array may express the dependency more accurately, provided the component actually owns the markup in both cases.
Do not immediately make the asset global. First prove whether the second page uses the expected component and attachment path.
Common mistakes
- Referencing
mytheme/product-cardwhen the declared key or machine name differs. - Using a path relative to the repository root rather than the extension root.
- Editing a file outside the active theme or module.
- Adding a dependency by file path instead of by library name.
- Attaching everything globally to avoid understanding a conditional render path.
- Clearing caches before checking the browser response or YAML source.
- Assuming a 200 response means the CSS selector matches or JavaScript completed successfully.
My Take
The asset library system is useful because it lets a page declare what it needs, but it also means “the file is there” is only the first check. Follow the chain from machine name to definition to attachment to browser request; each step gives you a concrete observation and keeps fixes focused.
Bottom Line
Verify the file and library name, inspect the attachment point, then confirm the asset request in the browser. Clear the appropriate cache only after the source checks out, and test both the page that needs the asset and one that should not load it.