CIRCUIT

Debugging AEM Sling Resource Resolution With Sling Tooling

When an AEM component renders the wrong markup, returns a 404, or appears to ignore a recently deployed script, the cause is often Sling resource resolution rather than Java code. Sling decides which resource, script, servlet, or URL mapping should handle a request by evaluating several layers of repository structure and request metadata. A small mismatch in a path, selector, extension, or resource type can send execution somewhere unexpected.

This is the kind of practical engineering problem explored through workshops and recordings on the CIRCUIT conference archive, which brings together AEM developers, architects, Java engineers, and systems specialists. For Australian teams working across Sydney, Melbourne, Brisbane, or Perth, a disciplined resolution workflow is especially useful when local authoring environments, cloud infrastructure, and production content services are separated by different deployment schedules and network conditions.

Start With The Resource, Not The Component

Sling begins with the requested URL and resolves it to a JCR resource. That resource may represent a page, an asset, a content fragment, a synthetic resource, or a node created by a custom provider. The resource path is the foundation for every later decision, so the first debugging task is to establish what Sling believes the URL means.

A request such as /content/example/au/en/products.html is not automatically mapped to a component because its name resembles a page. Sling examines the resource at that path, reads properties such as sling:resourceType and sling:resourceSuperType, then searches for a matching script or servlet. If the property is missing, points to an unavailable type, or differs between author and publish, the rendered result may fall back to an unexpected implementation.

Use CRXDE Lite or repository tooling to inspect the exact node, its properties, parent structure, and child nodes. Check the spelling and case of resource types carefully. A path under /apps/project/components/page is different from one under /apps/project/component/page, and a component deployed beneath an incorrect run mode may exist in the repository without being available on the instance handling the request.

Understand The Resolution Chain

Sling resource resolution has two related stages. Resource resolution converts a URL into a resource, while script or servlet resolution determines how that resource is rendered or processed. Confusing these stages can lead developers to edit a component script when the real issue is a URL mapping or an incorrect repository path.

After Sling identifies a resource, it considers selectors, extension, method, and resource type. A request ending in .html can select an HTML rendering script, while selectors such as .model or .print may choose a more specific implementation. A servlet registered by resource type, selector, extension, or path can also take precedence, depending on its registration and the request.

The resource super type adds another layer. An application component may inherit behaviour from a Core Component or a project base component, allowing Sling to search the supertype when it cannot find a local script. This is convenient, but it can conceal deployment errors: an incorrect sling:resourceSuperType may produce valid-looking output from an older implementation rather than an obvious failure.

Use Sling Tooling To Expose Decisions

The Sling Resource Resolver console is one of the most direct diagnostic tools available in AEM. On suitable development or admin environments, the resolver test interface can show how a URL is mapped, what resource is found, and how mappings behave in both directions. It helps distinguish an incoming URL problem from a rendering problem.

Repository browsers, Eclipse-based Sling tooling, CRXDE Lite, HTTP clients, and AEM loggers work best as a single toolkit. Use a controlled request with curl or a browser, inspect the resulting headers and status code, then compare the URL with the resolver output. Follow that by checking the resource type and the script search path. This creates evidence for each decision instead of relying on a guess based on the visible page.

Enable focused logging for Sling resource resolution and servlet resolution in a lower environment. Excessive DEBUG logging on a busy production publisher can create noise and operational risk, while targeted logging around a single request can reveal search paths, mappings, and script selection. Record the instance, run mode, request URL, selectors, extension, and HTTP method so another engineer can reproduce the result.

Read Script Search Paths Carefully

AEM usually searches application code beneath /apps before foundation code beneath /libs. That ordering supports overlays and project-specific implementations, but it also means that an old script, an accidental overlay, or a package installed in the wrong location can change behaviour without any Java compilation error.

Inspect the complete path implied by the resource type. If the resource type is project/components/content/hero, Sling may search under the configured script roots for that relative path and then apply selectors and extensions. Compare the expected script with the one actually found. Pay attention to .html, .jsp, and .esp files, as well as scripts with selector-specific names.

A common Australian delivery pattern involves separate author, publish, dispatcher, and CDN layers serving content to customers from different states. Test at each layer. A dispatcher rule can remove selectors, reject extensions, or cache a response that makes a Sling issue appear intermittent. A Melbourne author instance and a Sydney publish instance may also contain different package versions if a release was promoted unevenly.

Diagnose Mappings, Selectors, And Caches

Mapping rules can rewrite incoming URLs before Sling reaches the repository. Configuration beneath /etc/map in older AEM versions, or the relevant resource resolver mapping configuration in newer deployments, may convert public URLs into internal paths. Vanity paths and aliases can produce similar effects. Always compare the public URL with the internal resource path shown by the resolver tools.

Selectors deserve special attention because they are often introduced by front-end requirements. A request such as /content/site/page.print.html does not resolve like /content/site/page.html; it asks Sling to consider a print selector. Custom JSON, model, mobile, and feed endpoints may use several selector combinations, and a servlet registered for one combination can intercept a request intended for a component script.

Clear or bypass caches during testing, but do not treat cache clearing as a fix. Dispatcher and CDN caches can preserve an earlier response after a component deployment, particularly when cache invalidation rules differ between Australian staging and production environments. Capture an uncached request, inspect response headers, and confirm that the request reaches the intended publish instance before changing repository code.

Connect Debugging With Deployment Practice

Resolution defects frequently appear after content migrations, package refactoring, or AEM upgrades. A component can retain an old resource type while its implementation moves to a new namespace, or a package filter can omit a supporting script. Before changing code, compare the deployed repository structure with the source package and inspect installation logs for rejected or overwritten files.

Upgrade work deserves a separate comparison of resolver configuration and component inheritance. Teams planning a move between AEM releases can use these migration notes to place resource resolution checks alongside package compatibility, repository changes, and configuration review. The important principle is to test actual requests after deployment rather than assuming that a successful package installation proves equivalent behaviour.

For Australian organisations, deployment windows may be coordinated around Sydney business hours while retail, education, or government services operate nationally. A resolution change that appears harmless during a quiet morning can affect cached pages, campaign launches, or authoring teams in Adelaide and Perth. Keep a small set of representative URLs for each site, locale, selector, and component type, then run them against author, publish, dispatcher, and CDN endpoints.

Build A Repeatable Resolution Routine

A reliable investigation should leave behind a short record of what Sling did and why. Save the failing URL, resolved resource path, resource type, super type, selector list, extension, HTTP method, selected script or servlet, instance identity, and cache status. This information turns a vague rendering defect into a reproducible engineering case.

Use the following practices when diagnosing a difficult request:

  • Test the exact URL, including selectors, extension, suffix, query parameters, and HTTP method.
  • Confirm the resolved repository resource and inspect its sling:resourceType and sling:resourceSuperType.
  • Use the resolver console and focused Sling logs before editing component code.
  • Compare /apps, /libs, package filters, run modes, and deployed bundle versions across environments.
  • Test through publish, dispatcher, and CDN layers with cache headers recorded.

Once the direct cause is identified, add a regression test or deployment check for the affected resource type. A small automated request suite can detect missing scripts, incorrect mappings, and accidental overlays before a release reaches customers. It also gives distributed teams a shared diagnostic language when engineers are working across Australian offices or with an offshore implementation partner.

Apply this workflow to one failing AEM request at a time, verify the resolution chain at every infrastructure layer, and preserve the evidence in the project runbook. Explore the conference recordings and technical material on CIRCUIT to deepen that practice, then turn the resulting checks into repeatable deployment and support procedures for your AEM platform.