8.4 Environment Troubleshooting, Web Console & Developer Console

8.4 Environment Troubleshooting, Web Console & Developer Console

Core Principle: Choose the diagnostic surface that matches both the symptom and the hosting model. The local SDK and AEM 6.5 expose the Felix Web Console. AEM as a Cloud Service stage and production environments use the read-only Developer Console and Repository Browser; they do not provide unrestricted Web Console access.

Sling Servlet and Script Resolution

Sling resolves a request from the resource path, resource type, selectors, extension, suffix, and HTTP method. A path servlet can also match an explicitly registered servlet path.

On a local SDK or an AEM 6.5 instance, use /system/console/servletresolver. Enter the request path and method to see the selected servlet or script and competing candidates. This is the right first tool for:

• a servlet that returns 404 or 405;
• an unexpected script winning over a custom servlet;
• selector or extension mismatches;
• a resource type or supertype that resolves to the wrong renderer.

In the AEM as a Cloud Service Developer Console, use the Servlets view. It accepts a path with selectors and extension plus GET or POST and returns handlers in resolution order. If another servlet has a more specific registration or higher ranking, the result makes that visible.

Felix Web Console for Local SDK and AEM 6.5

The Web Console at /system/console is a mutable administrative tool and is appropriate only where the environment permits it.

Bundles

The Bundles view shows Installed, Resolved, and Active states. An Installed bundle often has an unresolved Import-Package requirement. Inspect its imports and version ranges, then confirm that an active bundle exports the required package. Do not try to solve an OSGi wiring failure by rebuilding indexes or clearing Dispatcher cache.

OSGi Components and Services

The Components view shows whether a Declarative Services component is active, satisfied, or unsatisfied. An unsatisfied mandatory reference means no matching service is available, the target filter excludes the available service, or the provider is itself inactive. A delayed component can be satisfied but not yet active until its service is requested.

Configuration Manager

Configuration Manager shows effective Configuration Admin values. In Cloud Service, configuration is immutable at runtime and source-controlled; use the Developer Console Configurations view to verify what was deployed rather than attempting a production edit.

AEM as a Cloud Service Developer Console

Open the Developer Console from the environment menu in Cloud Manager. It is read-only and requires the appropriate Cloud Manager and AEM product-profile permissions.

The current console provides:

• OSGi Bundles and Java Packages: Search deployed bundles, imports, exports, and package versions.
• Configurations: Inspect active configuration properties and environment-variable substitutions.
• Servlets: Test GET or POST resolution and compare registered handlers.
• Services and OSGi Components: Inspect providers, consumers, component state, and unsatisfied references.
• Repository Browser: Open a read-only view of repository content for an authorized tier.
• Status Dumps / Queries: Download text or JSON state for bundles, packages, configurations, services, components, Sling Jobs, and Oak definitions; open query-performance tooling.

The console reports the health of an environment tier. Adobe explicitly notes that the current console does not expose individual pod status. Do not base a troubleshooting procedure on selecting a named pod or taking a per-pod snapshot from the console.

Oak Query Diagnosis

A traversal warning or slow repository query belongs in query tooling, not in the bundle console. Use Query Performance to inspect popular and slow queries and run Explain on the exact statement. A useful plan names an appropriate index and estimated cost. A traversal plan indicates that no suitable index covers the path, node type, and property restrictions.

For custom indexes on AEM as a Cloud Service, deploy a supported custom index definition through the application and increment its version when the definition changes. Do not toggle reindex flags manually in production or assume the raw Oak-definition dump displays every merged index detail.

Thread Dumps and High CPU

On a local or self-managed AEM system, thread dumps can be captured with JVM tools or local Web Console facilities. AEM as a Cloud Service is different: Adobe collects thread dumps continuously, but current documentation says customers cannot download them in a self-service manner. For a Cloud Service CPU, deadlock, or stuck-thread incident:

1. Record the exact start and end time, environment, tier, request paths, and observed impact.
2. Preserve relevant aemrequest, aemerror, and Dispatcher logs for the same window.
3. Open an AEM Support case and request the thread dumps for that time window.
4. Correlate repeated runnable or blocked stacks with request latency and recent code or index changes.

Diagnostic Routing Matrix

The reliable exam pattern is symptom to tool: resolution issues go to servlet diagnostics, wiring issues to bundles/packages, activation issues to components/services, and query issues to Explain or Query Performance.