404 issues with ClientLibs

[PriyaNair1]

We are using AEM AMS and facing 404 issues with ClientLibs (e.g., /etc.clientlibs) even though the dispatcher filter is already allowing them. What could be the reason?

[SantoshSai]

Hi @PriyaNair1,

I think, the issue may not be with the dispatcher alone.

Here are several potential root causes and how to resolve them:

1. ClientLibs not replicated to publish

Even if filters are in place, the actual content (clientlibs) must exist on the publish instance.

Check:

• On the publish instance, verify if /etc.clientlibs, /apps, or /libs are accessible.

• Use CRXDE or /libs/granite/ui/content/dumplibs.rebuild.html to see if clientlibs are available.

If missing, re-deploy or re-activate from Author to Publish.

2. Dispatcher cache not cleared

Sometimes the clientlib file was cached as 404 during an earlier request before content deployment.

Solution:

• Clear dispatcher cache for /etc.clientlibs, /apps, or specific paths like /etc.clientlibs/site/clientlibs/main.css.

3. Incorrect rewrite/vanity/redirect rules

Rewrite or redirect rules in Apache might be interfering, even if dispatcher filter allows it.

Inspect your rewrite.rules or vhost config for misbehaving redirects affecting /etc.clientlibs.

4. File system permissions (AMS specific)

In Adobe Managed Services (AMS), file system permissions or incorrect symbolic links in the dispatcher docroot could lead to 404s.

Check:

• The symlinks in dispatcher cache path resolve correctly.

• You have permissions and correct owner/group on all docroot folders.

Hope that helps!

[PriyaNair1]

@SantoshSai I have verified all of the above points as you mentioned but still no luck.

[SantoshSai · Accepted solution]

@PriyaNair1 

Can you confirm whether read permissions are granted to the Anonymous user on the publisher instance?

A 403 or 404 error can occur if the requested resource is not accessible to unauthenticated users. This often happens in the publish environment, where the Anonymous user (which represents all unauthenticated users) needs explicit read access to /etc, /etc.clientlibs, or any custom path serving clientlibs or assets.

[ShivamKumar]

Hi @PriyaNair1 ,

Please verify these points also - 

1. ClientLibs Embedded Incorrectly or Missing Dependencies

If a parent clientlib embeds other libraries via categories,  and one of the embedded clientlibs is missing or not replicated to the publish instance, it can result in 404 errors even if the top-level clientlib exists.

Check:

• The embed and dependencies properties in the cq:ClientLibraryFolder node.

• Ensure all referenced clientlibs are present and published.

---

2. ClientLib Proxy Servlet Misconfiguration

If you're relying on the proxy servlet (/etc.clientlibs), verify:

Check:

• The OSGi configuration org.apache.sling.servlets.resolver.SlingServletResolver has correct executionPaths.

• No filters, servlets, or dispatcher rules are unintentionally blocking /etc.clientlibs.

---

3. CSRF Filter Blocking Requests

Sometimes the CSRF filter in AEM blocks access to /etc.clientlibs if headers or referrer settings are unexpected.

Check:

• Look for CSRF-related rejections in error.log.

• Review configuration at /system/console/configMgr/com.adobe.granite.csrf.impl.CSRFFilter.

---

4. Content Security Policy (CSP) Blocking Assets

If a restrictive CSP header is set, it may prevent browsers from loading assets from /etc.clientlibs.

Check:

• HTTP response headers for Content-Security-Policy.

• Confirm /etc.clientlibs is allowed in the CSP rules.

---

5. Missing ClientLib Categories in HTML Output

The expected clientlibs may not appear in the final HTML if:

• There's a mismatch between author and publish content.

• The component or template logic (HTL/Sightly) conditionally omits the clientlib.

Check:

• View the rendered page source and look for missing <link> or <script> tags for /etc.clientlibs.

6. Directly Test via Browser Dev Tools

Use Chrome DevTools (Network tab) or curl to request:
/etc.clientlibs/site/clientlibs/clientlib-name.css

Interpret Results:

• If it returns 404 only on publish, check for missing replication or failed builds.

• If it returns 404 despite being built, enable detailed dispatcher logging or  mod_rewrite debugging in Apache to trace the request path.

Try these and let me know if something works.

Thanks.

[AmitVishwakarma]

Hi @PriyaNair1 ,

Try below steps:

1. Confirm ClientLib Availability on Publish Instance

Check if the ClientLibs exist on the publish instance:

Access:

https://<publish-host>/etc.clientlibs/<your-site>/clientlibs/clientlib-site.css

If 404:

Go to CRXDE Lite on Publish: https://<publish-host>/crx/de

Confirm that /apps, /etc.clientlibs, /etc/designs, or /libs contain the relevant paths.

Fix:
If not present, activate (replicate) the clientlibs folders from Author to Publish:

From AEM Author: Go to /apps/your-project and /etc.clientlibs/your-project, right-click > Replicate.

2. Manually Rebuild ClientLibs (If Missing on Publish)
In rare cases, clientlibs are not built on publish properly.
Fix:
Hit the rebuild servlet on Publish:

https://<publish-host>/libs/granite/ui/content/dumplibs.rebuild.html
​

Click Rebuild All.
Then clear dispatcher cache for /etc.clientlibs.

3. Clear Dispatcher Cache (Forcefully)
If clientlibs were missing during a prior request, dispatcher may have cached the 404.
Fix:
SSH into dispatcher or AMS web tier.
Run:

rm -rf /mnt/var/www/html/etc.clientlibs/
​

Or target specific path:

rm -rf /mnt/var/www/html/etc.clientlibs/your-site

Then reload the page or curl the asset directly to re-cache.

4. Dispatcher Filters – Double Check

In dispatcher.any, ensure this filter exists:

/0009 {
  /type "allow"
  /url "/etc.clientlibs/*"
}

Fix:
If it exists, also confirm there's no earlier deny rule accidentally overriding it.

5. Apache Rewrite Rules (Check for Interference)
Sometimes rewrite rules or virtual host redirects can interfere.
Fix:
In your Apache .vhost or rewrite.rules, make sure you’re not rewriting or redirecting /etc.clientlibs unintentionally.
Add this bypass rule at the top:

RewriteCond %{REQUEST_URI} ^/etc.clientlibs/
RewriteRule ^ - [L]
​

6. Verify File System Symlinks (AMS-Specific)

AMS uses symlinks in the docroot to serve content from the dispatcher cache.

Fix:

SSH into the dispatcher.

Check:

ls -l /mnt/var/www/html/etc.clientlibs

Make sure it points to a valid cache location.

If broken: restart dispatcher flush agent or invalidate cache.

7. Anonymous User Permissions on Publish
AEM Publish often restricts access to unauthenticated (Anonymous) users.
Fix:
Go to AEM Publish /useradmin (https://<publish-host>/useradmin)
Search for Anonymous user.
  - Go to /etc.clientlibs, /apps, /etc.designs, etc.
  - Grant Read access explicitly.
  - A 403 may also result in a 404-looking response depending on dispatcher behavior.

Optional (But Recommended)
Enable Dispatcher Flush Agents (on Author)
If you make changes to clientlibs, always ensure you:
  - Flush the cache via replication using a dispatcher flush agent.

Regards,
Amit