AEM enterprise manager, AMS not cloud. I had to restart custom bundle in order to author pages.

[fionas76543059]

hi folks,

I had to manually restart my custom bundle on the UAT Author instance. (It was in INSTALLED state)

(This was after a deployment and some restarts of the server.)

However, I didn't have this problem with other environments with the same code.

After that I was able to Author a page as usual.

Any ideas what caused this?

I found the following log error message that might be relevant.

thanks

Fiona

03.06.2025 08:28:09.919 *ERROR* [10.44.31.103 [1748939286758] GET /content/xxx/homepage.html HTTP/1.1] com.day.cq.wcm.core.impl.WCMDeveloperModeFilter Error during include of SlingRequestPathInfo: path='/content/xxxx/homepage/jcr:content', selectorString='null', extension='html', suffix='null'
org.apache.sling.scripting.sightly.SightlyException: Compilation errors in org/apache/sling/scripting/sightly/apps/xxx/components/page/basepage/basepage__002e__html.java:
Line 40, column 1811 : com.xxx.use.xxxxUse cannot be resolved to a type
at org.apache.sling.scripting.sightly.impl.engine.compiled.SlingHTLMasterCompiler.compileSource(SlingHTLMasterCompiler.java:356) [org.apache.sling.scripting.sightly:1.4.24.140]
at org.apache.sling.scripting.sightly.impl.engine.compiled.SlingHTLMasterCompiler.compileHTLScript(SlingHTLMasterCompiler.java:255) [org.apache.sling.scripting.sightly:1.4.24.140]
at org.apache.sling.scripting.sightly.impl.engine.SightlyScriptEngine.compile(SightlyScriptEngine.java:66) [org.apache.sling.scripting.sightly:1.4.24.140]
at org.apache.sling.scripting.core.impl.DefaultSlingScript.call(DefaultSlingScript.java:386) [org.apache.sling.scripting.core:2.4.8]

[giuseppebag · Accepted solution]

hi @fionas76543059, 

your issue indicates that the HTL (Sightly) script is referencing a Java Use-API class that the Sling scripting engine cannot find or load at runtime.

The reason this issue occurs only in UAT/Prod environments and not in Dev/QA I'm unclear. Here are some possible explanations:

• bundle resolution and classloading issues: the custom bundle containing com.xxx.use.xxxxuse is not active or fully resolved when the HTL engine tries to compile the script. this causes the compilation error and the bundle stays in installed state.

• dependency or version mismatch: your custom bundle may depend on other bundles or core AEM bundles that are different versions or missing in UAT/prod.

• class visibility: the package com.xxx.use might not be exported properly in the bundle's export-package or the bundle is not correctly deployed.

[AmitVishwakarma]

Hi @fionas76543059 ,

The log shows an error like:

com.xxx.use.xxxxUse cannot be resolved to a type

This indicates that AEM couldn't find or load the custom Java class (xxxxUse) referenced in your HTL.

A bundle in the INSTALLED state means:

  - OSGi recognized the bundle, but dependency resolution failed. That is, required packages/classes weren't available (or available yet) at startup.

This typically happens due to:

  - Missing or incorrectly exported package in the bundle MANIFEST.MF

  - Timing issues during startup your custom bundle may depend on another bundle that wasn't active yet.

  - ClassLoader mismatch or cached class inconsistency post-deployment.

  - AEM doesn't automatically refresh a bundle stuck in INSTALLED you must restart it manually or automate it.

Try below options:

Option 1: Add Missing Package(s) in MANIFEST.MF

Check your bnd.bnd or pom.xml export settings.
If the Java class com.xxx.use.xxxxUse is not in an exported package, AEM cannot resolve it in HTL.

How to check:
  - Go to /system/console/bundles => Find your bundle
  - Click => Inspect Exported Packages
  - Ensure the package where xxxxUse class is located is listed there

If not, in your bnd.bnd or pom.xml:

<Export-Package>
  com.xxx.use.*
</Export-Package>

Or in bnd.bnd:

Export-Package: com.xxx.use.*

Rebuild and deploy again.

Option 2: Make Sure All Dependencies Are ACTIVE

If your custom bundle depends on another bundle (say a core bundle), and that is not yet active when your custom bundle is started, it will be stuck in INSTALLED.

Solution:

  - Set proper bundle start levels if needed

  - Ensure order of deployment is correct

  - Run this after deployment to auto-refresh installed bundles

curl -u admin:admin -F action=refresh /system/console/bundles

Option 3: Automate Restart of INSTALLED Bundles

Add a post-deploy script or Jenkins task

curl -u admin:admin http://localhost:4502/system/console/bundles/my.custom.bundle \
  -d action=stop

curl -u admin:admin http://localhost:4502/system/console/bundles/my.custom.bundle \
  -d action=start

Or, script all INSTALLED bundles:

for bundle in $(curl -u admin:admin -s http://localhost:4502/system/console/bundles.json | jq -r '.data[] | select(.state == "Installed") | .symbolicName'); do
  curl -u admin:admin -d action=refresh http://localhost:4502/system/console/bundles/$bundle
done

Regards,

Amit

[fionas76543059]

Thanks for the useful info!