8.2 Debugging Client-Side Libraries & Granite Dumplibs

Adobe Certified Professional - AEM Sites Developer AD0-E128

Track your progress as you read

Finished sections get a check mark.

1 Chapter 1: Dispatcher Farm & Multi-Site Configuration

1.1 AEM Dispatcher Configuration & Caching Fundamentals 1.2 Multi-Site Management (MSM) & Blueprint/Live Copy Architecture 1.3 OSGi Configuration Management & Run Modes (.cfg.json)

2 Chapter 2: Oak Indexing & Custom Logging

2.1 Custom Oak Index Definitions & Lucene Query Optimization 2.2 AEM Custom Logging, Logback Configurations & Request Tracing

3 Chapter 3: Component Architecture, HTL & Client Libraries

3.1 Core Components & Proxy Component Pattern 3.2 HTL (HTML Template Language) Block Statements & Context-Aware Escaping 3.3 Client-Side Libraries (Clientlibs) Architecture & Management

4 Chapter 4: Sling Models & OSGi Declarative Services

4.1 Sling Models Framework, Injectors & Model Exporter 4.2 OSGi Declarative Services, Component Lifecycle & Service Rankings

5 Chapter 5: Templates, Fragments & Business Workflows

5.1 Editable Templates, Structure, Initial Content & Content Policies 5.2 Content Fragments, Experience Fragments & Headless Delivery 5.3 AEM Workflows, Custom Process Steps & Launchers

6 Chapter 6: Build, Packaging & Cloud Manager CI/CD

6.1 Maven Project Structure & AEM Project Archetype 6.2 Content Package Types, Packaging Rules & FileVault Validation 6.3 Cloud Manager CI/CD Pipelines & Quality Gates 6.4 Rapid Development Environments (RDE) & Sling Repoinit Scripts

7 Chapter 7: Environment Maintenance & Content Distribution

7.1 AEM Maintenance Releases & Cloud Service Version Updates 7.2 AEM Deployment Topologies & Cloud Architecture 7.3 Replication Agents & Sling Content Distribution 7.4 Repository Maintenance: Revision Cleanup, Compaction & Purge Tasks

8 Chapter 8: Analyzing, Debugging & Diagnostic Tools

8.1 System Log Analysis & Diagnostic Tooling 8.2 Debugging Client-Side Libraries & Granite Dumplibs 8.3 Dispatcher Caching Diagnostics, X-Cache-Info & Local Validation 8.4 Environment Troubleshooting, Web Console & Developer Console

8.2 Debugging Client-Side Libraries & Granite Dumplibs

Key Takeaways Explain This Topic AI

The Granite Dumplibs diagnostic console at /libs/granite/ui/content/dumplibs.html provides tools to search clientlibs by category, inspect recursive dependency and embed trees, test compiled output, and force clientlib cache rebuilding.

Appending ?debugClientLibs=true exposes debuggable clientlib output and source origins so embedded files and generated resources can be inspected without relying on a minified production bundle.

Configuring dependencies establishes prerequisite loading where external clientlibs load before the dependent library, whereas embed merges the code directly into the compiled bundle, risking code bloat and duplicate script execution.

Minification failures in GCC (Google Closure Compiler) or YUI compressors commonly stem from unsupported modern JavaScript syntax (such as optional chaining or unpolyfilled ES6+ features), causing minifier aborts in error.log and broken clientlib delivery.

Long-lived clientlib caching requires an explicit versioned or long-cache URL strategy plus matching cache headers; allowProxy alone does not create immutable hashed URLs.

Last updated: September 2026

8.2 Debugging Client-Side Libraries & Granite Dumplibs

Core Principle: Client-Side Libraries ( clientlibs ) manage the delivery of CSS and JavaScript in AEM Sites applications. While clientlibs offer concatenation, minification, dependency management, and URL fingerprinting, debugging them can be challenging when scripts fail to execute, styles collide, or minification aborts silently. Mastering diagnostic tools like Granite Dumplibs ( /libs/granite/ui/content/dumplibs.html ) and the ?debugClientLibs=true query parameter is essential for rapid troubleshooting.

1. Clientlib Architecture & Compilation Lifecycle

An AEM client library is a repository node of type cq:ClientLibraryFolder . The Granite HTML Client Library Manager processes clientlib nodes into optimized CSS and JavaScript bundles through an automated compilation lifecycle: +-------------------------------------------------------------------------+

| cq:ClientLibraryFolder (/apps/wknd/clientlibs/clientlib-site) |
| - categories: ["wknd.site"] |
| - dependencies: ["core.wcm.components.commons"] |
| - embed: ["wknd.grid"] |
| - allowProxy: true |
+-------------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------------+
| Granite HTML Client Library Manager |
| 1. Parse js.txt and css.txt index files |
| 2. Resolve recursive dependency graph |
| 3. Inline embedded libraries (embed) |
| 4. Run CSS/JS Processors (GCC / YUI Minification & Preprocessors) |
| 5. Cache compiled payloads under /var/clientlibs |
+-------------------------------------------------------------------------+
|
v
+-------------------------------------------------------------------------+
| Proxy Delivery Layer |
| /etc.clientlibs/wknd/clientlibs/clientlib-site.lc-1a2b3c-lc.min.js |
+-------------------------------------------------------------------------+
Critical Node Properties

Property Type Operational Function

categories String[] Unique identifiers used by HTL templates ( data-sly-use.clientlib or <sly data-sly-call="${clientlib.all @ categories='wknd.site'}"/> ) to request clientlibs. Multiple folders can share the same category name.

dependencies String[] Clientlib categories that must execute before this clientlib. Loaded as separate prerequisite <script> / <link> tags ahead in the document head.

embed String[] Clientlib categories whose raw source files are inlined directly into this library's single combined bundle payload.

allowProxy Boolean When true , exposes clientlibs stored under /apps safely via the public /etc.clientlibs/ proxy servlet path, protecting internal repository structures from anonymous access.

jsProcessor String[] Configures custom JavaScript minifiers and transpilers (e.g. [default:none,min:none] ).

cssProcessor String[] Configures CSS minification and preprocessor engines.

2. Granite Dumplibs Diagnostic Console ( /libs/granite/ui/content/dumplibs.html )

The Granite Dumplibs console is AEM's built-in administrative suite for inspecting, validating, and debugging the runtime state of all registered client libraries. Located at: / l i b s / g r a n i t e / u i / c o n t e n t / d u m p l i b s . h t m l \mathbf{/libs/granite/ui/content/dumplibs.html} /libs/granite/ui/content/dumplibs.html

Primary Console Tabs & Diagnostic Tools +-----------------------------------------------------------------------+

| Granite Dumplibs Console |
+-----------------------------------------------------------------------+
| [By Category] | [By Path] | [Dependencies] | [Test Output] | [Rebuild]|
+-----------------------------------------------------------------------+
1. By Category View

Displays an alphabetical index of all clientlib categories currently registered in the OSGi clientlib service registry.

Diagnostic Capability : Search for any category (e.g. wknd.site ). The tool reveals every cq:ClientLibraryFolder path registered under that category, exposing accidental category collisions where multiple third-party or legacy packages register duplicate categories.

2. By Path View

Lists all physical repository paths containing cq:ClientLibraryFolder nodes under /apps , /libs , and /etc .

Displays the primary type, category names, dependency declarations, and embed lists for each folder.

3. Dependencies Graph View

Evaluates the complete recursive dependency tree for any specified category.

Diagnostic Capability : Identifies cyclic dependencies (e.g. Library A depends on B, which depends on A) and highlights unresolved dependencies in red when a declared category does not exist in the repository.

4. Test Output & Print Channel View

Allows developers to simulate HTL clientlib inclusions for both CSS and JS channels.

Outputs the raw, concatenated, and minified stream directly into the browser, enabling developers to confirm whether a specific .js file declared in js.txt was successfully bundled into the output.

5. Rebuild Client Libraries ( /libs/granite/ui/content/dumplibs.rebuild.html )

In local development, AEM caches compiled clientlib artifacts in memory and under /var/clientlibs .

Clicking Invalidate Caches or Rebuild Libraries purges the cached artifacts and forces the HTML Client Library Manager to re-parse all js.txt and css.txt files from JCR sources.

3. In-Browser Diagnostics: ?debugClientLibs=true

In standard production and staging environments, AEM concatenates all source files into a single bundle and applies minification. When a JavaScript runtime exception occurs (e.g. TypeError: Cannot read properties of undefined ), the browser's Developer Tools stack trace points to a minified bundle line (e.g. clientlib-site.min.js:1:48201 ), making root-cause analysis nearly impossible.

The Debug Parameter

Appending ?debugClientLibs=true to any page URL completely alters the Client Library Manager's output: https://wknd.site/us/en/adventure.html ? d e b u g C l i e n t L i b s = t r u e \text{https://wknd.site/us/en/adventure.html}\mathbf{?debugClientLibs=true} https://wknd.site/us/en/adventure.html ? debugClientLibs = true

Operational Effects of ?debugClientLibs=true :

Exposes source composition : Generated debug output identifies or references the underlying source files instead of hiding them behind only the optimized production payload.

Avoids the normal minified view : This makes original source and generated imports easier to inspect.

Reveals origin paths : Use page source, the generated library, and browser developer tools to trace files back to their clientlib location:

<script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site/js/navigation.js"></script>

<script type="text/javascript" src="/etc.clientlibs/wknd/clientlibs/clientlib-site/js/carousel.js"></script>
Developer Workflow in Browser DevTools

Open the browser Console tab: Stack traces now reference the exact source file and line number (e.g. navigation.js:42 ).

Open the Sources / Debugger tab: Set breakpoints, inspect local variables, and step through functions directly without generating client-side source maps.

Inspect the Network waterfall: Determine whether a specific individual script is experiencing 404 Not Found errors or high download latency.

4. Common Clientlib Pathologies & Remediation
1. Load Order Problems: dependencies vs. embed

A frequent architectural flaw in AEM Sites is the misuse of embed when dependencies is required. +-----------------------------------+ +-----------------------------------+

| dependencies | | embed |
+-----------------------------------+ +-----------------------------------+
| - Loaded as SEPARATE HTTP tags | | - Inlined DIRECTLY into bundle |
| - Guarantees execution ORDER | | - Single combined HTTP payload |
| - Shared across multiple libs | | - Duplicates code if re-embedded |
| - Best for: jQuery, Core Commons | | - Best for: Micro-plugins, icons |
+-----------------------------------+ +-----------------------------------+

Warning

The Embed Duplication Hazard: If clientlib-header embeds jquery and clientlib-footer also embeds jquery , jQuery is downloaded and executed twice . The second execution overwrites the global window.$ object, destroying all event listeners registered by plugins initialized during the first execution!

Remediation Rule: Always use dependencies for shared foundational libraries, framework runtimes, and Core Component clientlibs. Restrict embed to private sub-modules that belong strictly to that specific clientlib.

2. Missing Category Dependencies & ReferenceError

When an AEM page loads, the browser console reports: Uncaught ReferenceError: $ is not defined or Uncaught ReferenceError: Granite is not defined .

Root Cause Analysis:

The site clientlib executes code calling $(document).ready(...) , but the category core.wcm.components.commons.site.jquery was neither declared in the clientlib's dependencies property nor included in the page's HTML <head> .

Inspect the page template structure under /conf/wknd/settings/wcm/templates/.../structure or customheaderlibs.html . Verify that dependency clientlibs are loaded before component clientlibs.

3. Minification Engine Errors (GCC / YUI)

A developer adds modern ECMAScript features (e.g. optional chaining item?.name , nullish coalescing val ?? defaultVal , or ES6 arrow functions) to a clientlib file. In the browser, the script fails to execute, or the clientlib file returns HTTP 500.

Inspecting error.log : *ERROR* [0:0:0:0:0:0:0:1 [1695478900123] GET /etc.clientlibs/wknd/clientlib-site.min.js HTTP/1.1]

com.adobe.granite.ui.clientlibs.impl.HtmlLibraryManagerImpl Error during minification of
/apps/wknd/clientlibs/clientlib-site/js/checkout.js
com.google.javascript.jscomp.RhinoError: Parse error. syntax error at /apps/wknd/.../checkout.js line 15

Root Cause: AEM's built-in minifier (Google Closure Compiler or YUI) cannot parse modern ES syntax without transpilation. Remediation Options:

Transpile code to standard ES5/ES6 using Babel, Webpack, or Vite in the frontend build pipeline before copying to ui.apps .

Disable minification for that specific clientlib by setting jsProcessor=[default:none,min:none] on the cq:ClientLibraryFolder node.

4. Stale Clientlibs & Clientlib Fingerprinting

Following a production code release, end users report broken layouts or missing features until they perform a hard refresh ( Cmd+Shift+R or Ctrl+F5 ).

Root Cause: The browser and Dispatcher cached the old clientlib-site.min.js file with an aggressive Cache-Control: max-age=31536000 header. Dispatcher was not flushed, or the browser cache held the old URL.

The Solution: Configured Long-Cache Clientlib URLs When a project enables a supported long-cache clientlib URL strategy, the public URL can contain a version token: / e t c . c l i e n t l i b s / w k n d / c l i e n t l i b s / c l i e n t l i b − s i t e . l c − 1 a 2 b 3 c 4 d 5 e − l c . m i n . j s \mathbf{/etc.clientlibs/wknd/clientlibs/clientlib-site.lc-1a2b3c4d5e-lc.min.js} /etc.clientlibs/wknd/clientlibs/clientlib − site.lc − 1a2b3c4d5e − lc.min.js

The version token changes when the configured mechanism detects a new clientlib version.

The browser treats the new URL as a different resource.

Cache lifetime still follows the actual CDN, Dispatcher, and response-header configuration; do not infer immutable or infinite caching from allowProxy .

5. Diagnostic Summary Checklist

Problem Symptom Primary Diagnostic Tool Corrective Action

Minified JS stack trace gives unhelpful line numbers. Add ?debugClientLibs=true to page URL. Inspect individual source files in DevTools Sources tab.

Uncaught ReferenceError: ... is not defined . Check /libs/granite/ui/content/dumplibs.html Dependencies tab. Add missing category to dependencies array.

Duplicate scripts execute; global variables reset. Search Dumplibs By Category view. Eliminate duplicate embed declarations; switch to dependencies .

Minifier compilation error in error.log . Check error.log for HtmlLibraryManagerImpl . Transpile modern ES syntax or set jsProcessor=[default:none,min:none] .

Layout broken after deployment due to stale cache. Inspect page source for clientlib fingerprinting hash. Verify the configured long-cache URL mechanism, cache headers, and Dispatcher/CDN behavior.