#Problems & Solutions (AEM 6.5)

Tài liệu tổng hợp các vấn đề thường gặp và hướng giải quyết trong AEM 6.5.

Kiểm tra chung khi gặp lỗi:

• Kiểm tra tất cả log: error.log, stdout.log, request.log (đúng instance author/publish)
• Restart/reload/update bundle trong OSGi Console
• Restart instance nếu cần
• Xóa /var/classes và /var/clientlibs để force recompile
• Kiểm tra bundle status tại /system/console/bundles

#Component không hiển thị nút Edit trong edit mode (editor.html)

Giải pháp:

• Component thiếu cq:dialog hoặc cq:editConfig (cần ít nhất 1 trong 2), hoặc file XML bị malformed
• Component bị đánh dấu .hidden
• Component không được phép cho page/parsys hiện tại (kiểm tra cq:allowedComponents)
• Sai cq:designPath trên root page của site (Static Template)
• Với Editable Template: kiểm tra policy có cho phép component không (Template Editor > Structure > Policy)
• Thử clear browser cache và local storage

#Maven build lỗi MojoExecutionException

Lỗi này có nhiều nguyên nhân:

1. "Installation on http://localhost:4502/apps/abc/install failed" → Folder /apps/abc/install chưa tồn tại. Tạo thủ công trong CRXDE Lite.
2. "Connection refused" → Instance chưa chạy hoặc sai port.
3. "401 Unauthorized" → Sai credentials trong Maven settings hoặc pom.xml.
4. SSL error trên AMS/self-signed cert → Thêm -Dvault.relaxedSSLCheck=true vào lệnh mvn.

#Maven build lỗi SSL với self-signed certificate (AMS/Cloud)

sun.security.validator.ValidatorException: PKIX path building failed

Giải pháp: Thêm -Dvault.relaxedSSLCheck=true vào lệnh mvn:

mvn clean install -PautoInstallPackage -Dvault.relaxedSSLCheck=true

#Component không xuất hiện trong component list

Giải pháp:

• Thiếu cq:dialog hoặc cq:editConfig, hoặc XML bị lỗi (kiểm tra bằng CRXDE)
• Component bị đánh dấu .hidden (componentGroup trống hoặc bắt đầu bằng .)
• Component chưa được cho phép trong page template / policy
• cq:designPath thiếu hoặc sai trên root page (cho Static Template)
• Với Editable Template: component chưa được enable trong Template Editor

#404 trong console cho component đã bị xóa

Giải pháp:

• Clear local storage trên browser (component cũ có thể vẫn được cache)
• Reload page với Ctrl+Shift+R

#Thay đổi không xuất hiện trong JCR/CRXDE

• Vault (vlt) hoặc Maven chưa push thay đổi → Kiểm tra có lỗi XML không (ví dụ: & phải viết là &)
• File .content.xml bị sai cú pháp → Dùng CRXDE để validate
• Package filter không bao gồm path bị thay đổi

#Lỗi No renderer for extension html / cannot render resource SyntheticResource

org.apache.sling.servlets.get.impl.DefaultGetServlet No renderer for extension html

Resource/Component không tồn tại. Kiểm tra:

• Resource path có đúng không
• Resource type (sling:resourceType) trỏ đến component có thực không
• Bundle chứa component có Active không

#Lỗi import: Only a type can be imported ... resolves to a package

Only a type can be imported. com.example.MyService resolves to a package

Giải pháp:

• Kiểm tra bundle có Active không trong /system/console/bundles
• Bundle có export package chứa class đó không (OSGi > Packages)
• Xóa /var/classes để force recompile (xóa trực tiếp trong CRXDE hoặc restart bundle)

⚠️ /system/console/slingjsp đã bị xóa khỏi AEM 6.5. Dùng cách xóa /var/classes trực tiếp trong CRXDE hoặc restart bundle.

#Ảnh không hiển thị trên Dispatcher

• Kiểm tra ảnh có hiển thị trên Author/Publish không
• Kiểm tra Dispatcher cache rules (dispatcher.any) có flush đúng path không
• Kiểm tra có redirect rule nào trên Dispatcher chặn request không
• Kiểm tra header X-Dispatcher-Info để xác nhận cache behavior
• Invalidate cache thủ công: gửi POST đến http://dispatcher/dispatcher/invalidate.cache

#ClassNotFoundException khi chạy bundle

• Thiếu dependency trong pom.xml
• Dependency không được export bởi bundle cung cấp nó
• Thêm vào pom.xml với scope provided nếu đã có trong AEM container
• Kiểm tra package export tại /system/console/bundles > click vào bundle > xem Packages

#POST servlet trả về 403 Forbidden (từ Postman / API call)

• Thiếu authentication header
• Sling Referrer Filter block request → Vào /system/console/configMgr > Apache Sling Referrer Filter > bật Allow Empty hoặc thêm allowed host
• Đối với CSRF: thêm header CSRF-Token lấy từ /libs/granite/csrf/token.json

#AntiSamy warning trong log

AntiSamy warning: The a tag contained an attribute that we could not process.
The adhocenable attribute has been filtered out...

• Xác định attribute nào bị filter
• Nếu attribute hợp lệ (ví dụ: target="_blank"), thêm vào AntiSamy config: overlay /libs/cq/xssprotection/config.xml vào /apps/cq/xssprotection/config.xml

#editor.html trả về 404

• Kiểm tra node /libs/wcm/core/content/editor có tồn tại và đúng type không
• Kiểm tra bundle com.adobe.granite.ui.content có Active không
• Xóa browser cache/localStorage

#Taglib không resolve trong JSP

JasperException: The absolute uri: http://... cannot be resolved

• Bundle cung cấp taglib có Active không?
• JSP (legacy) trong AEM 6.5 ít dùng — cân nhắc chuyển sang HTL

#Ajax POST servlet trả về 302 Found

• Sling Form Post servlet (SlingPostServlet) có thể redirect sau khi POST nếu có :redirect parameter
• Kiểm tra request có chứa :formid hoặc :formstart không — bỏ chúng đi nếu không cần

#Unresolved constraint: osgi.wiring.package (version conflict)

• Dependency chưa tồn tại trong OSGi container → thử embed vào bundle
• Conflict version → dùng <Import-Package> với version range trong bnd.bnd hoặc maven-bundle-plugin
• Kiểm tra dependency graph tại /system/console/depfinder

#j_security_check trả về 403 / User login không hoạt động

org.apache.sling.auth.core.impl.SlingAuthenticator handleSecurity: AuthenticationHandler did not block request; access denied

• 301 redirect có thể làm mất auth header → Kiểm tra redirect config trên Dispatcher/CDN
• Kiểm tra /system/console/slingauth để xem thứ tự Authentication Handler
• Đảm bảo Login Token Expiration chưa hết hạn

#SAML Authentication trả về 403

• Kiểm tra tất cả config value có đúng type không: {Boolean}, {Long}, []
• service.ranking của SAML handler phải cao hơn Token Authentication Handler
• Kiểm tra /system/console/slingauth để xem thứ tự handler
• Theo dõi /system/console/events để xem LOGIN event và handler nào được dùng
• Config deploy qua config.author folder phải khớp hoàn toàn với giá trị manual trong configMgr

#XML parsing error: GenericArtifactHandler Error while parsing ...xml

• Thường do thiếu jcr:primaryType="nt:unstructured" trên một node trong dialog XML
• Kiểm tra từng field để đảm bảo XML hợp lệ
• Dùng CRXDE để validate cú pháp XML

#Cookie không xuất hiện dù response header trả về đúng

• Thêm tên Cookie vào danh sách exclude trong Adobe Granite Opt-Out Service (OSGi config)
• Không set Domain attribute trên cookie (để browser tự handle)
• Nếu dùng setSecure(true) nhưng request là HTTP → cookie sẽ không được set

#Không thể thêm trang vào Translation Project / project tạo với 0 trang

• Kiểm tra /etc/workflow/models/translation/translation_rules.xml có comment ở đầu file không → AEM không parse được, phải đặt comment bên trong <nodelist>
• Trong AEM 6.5: kiểm tra Translation Configuration tại Tools > Cloud Services > Translation Cloud Services

#EventHandler không được gọi

• Kiểm tra event có thực sự xảy ra không: /system/console/events
• EventHandler đã được register chưa: /system/console/components
• EventHandler có thể bị blacklist: kiểm tra OSGi config org.apache.felix.eventadmin.impl.EventAdmin → thuộc tính event.ignore.timeout
• Với Sling Job, kiểm tra queue tại /system/console/slingevent

#RTE config không hoạt động cho author

• Group contributors bị deny read trên rep:glob=apps/*/config/* theo mặc định của AEM → author không đọc được config node của cq:inplaceEditing
• Giải pháp: Thêm ACL allow cho group contributor tại /apps/<project>/components/** hoặc set ACL cụ thể cho path config
• Đây là security feature của AEM — cân nhắc kỹ trước khi override

#Lỗi khi publish: Failed to retrieve references for the selected page

NullPointerException in ContentPolicyReferenceProvider

• Có cq:policy property trỏ đến policy không tồn tại
• Kiểm tra trong CRXDE: tìm các cq:policy reference dưới /content/<site> và đảm bảo policy tương ứng tồn tại trong /conf/<site>/settings/wcm/policies

#Java process có I/O wait cao do MSM rollout

• Kiểm tra top command: nếu wa (io wait) liên tục > 30%
• Kiểm tra /system/console/events tìm Replication hoặc MSM event bất thường
• Kiểm tra /system/console/slingevent (Sling Job Queue) xem có job nào bị stuck không
• Tạm dừng MSM rollout scheduled task trong Maintenance Console

#i18n dictionary cache lỗi thời / string mới không được dịch

• Giải pháp 1: Deploy một thay đổi nhỏ vào dictionary để trigger reindex
• Giải pháp 2: Restart bundle Apache Sling Internationalization Support (org.apache.sling.i18n)
• Giải pháp 3: Xóa /var/eventing/slingi18n trong CRXDE rồi restart bundle

#SlingException: Cannot get DefaultSlingScript: null

• Root resource /content/<site> chưa được replicate lên Publish
• Kiểm tra replication queue tại /etc/replication.html
• Đảm bảo root page và các config node (jcr:content) đã được activated

#IntelliJ IDEA không resolve import từ AEM / Maven

• Chạy mvn eclipse:eclipse rồi reimport
• IDE > Maven > Reload All Maven Projects
• File > Invalidate Caches / Restart
• Đảm bảo <scope>provided</scope> đúng với các AEM API dependency

#Tạo OSGi Service đọc cấu hình (OSGi Config)

Cần tạo:

1. Config Interface (@ObjectClassDefinition) — định nghĩa các field config
2. Service Interface — define contract
3. Service Implementation — @Component, @Designate(ocd = MyConfig.class)

@ObjectClassDefinition(name = "My Service Config")
public @interface MyServiceConfig {
    @AttributeDefinition(name = "Host")
    String host_ip() default "localhost"; // dấu "." trong key dùng "_" trong method name

    @AttributeDefinition(name = "Port")
    int port() default 8080;
}

@Component(service = MyService.class)
@Designate(ocd = MyServiceConfig.class)
public class MyServiceImpl implements MyService {
    private MyServiceConfig config;

    @Activate
    protected void activate(MyServiceConfig config) {
        this.config = config;
    }
}

Lưu ý:

• Nếu key config có dấu . (ví dụ host.ip), dùng _ trong tên method: host_ip()
• Dùng annotation từ org.osgi.service.component.annotations (DS Annotations), không dùng Felix annotation cũ
• Deploy config bằng file .cfg.json (ưu tiên trong AEM 6.5+) hoặc .config file

Tham khảo:

• Configuring OSGi - Adobe Experience League

#Workflow không trigger / Workflow Launcher không hoạt động

• Kiểm tra Launcher đã enable chưa: Tools > Workflow > Launchers
• Kiểm tra điều kiện path và event type (Node Created / Node Modified / ...)
• Kiểm tra Workflow Model có valid không: Tools > Workflow > Models
• Xem Workflow history: /libs/cq/workflow/content/console.html > Instances

#Bundle ở trạng thái Installed thay vì Active

• Bundle đang chờ dependency → Kiểm tra tab Imported Packages của bundle tại /system/console/bundles
• Dùng /system/console/depfinder để tìm package nào đang thiếu
• Có thể cần embed dependency hoặc thêm vào pom.xml

#Replication Queue bị stuck (Publish không nhận content)

• Kiểm tra queue tại /etc/replication/agents.author/publish.html
• Kiểm tra Publish instance có đang chạy không
• Thử Retry hoặc Clear queue
• Kiểm tra Replication Agent config: URL, credentials, transport URI

#Slow query / Trang load chậm do thiếu Oak index

*WARN* ... Traversed 50000 nodes with filter Filter(...)

• Kiểm tra Query Performance Tool: /libs/granite/operations/content/diagnosistools/queryPerformance.html
• Tạo Oak Index phù hợp (lucene hoặc property index)
• Dùng EXPLAIN trong Query Debugger để phân tích query plan: /libs/cq/search/content/querydebug.html
• Tránh query trên property không có index, đặc biệt jcr:content/jcr:lastModified

#ContextHub không hoạt động

ℹ️ Client Context đã bị deprecated từ AEM 6.4. AEM 6.5 sử dụng ContextHub.

• Kiểm tra ContextHub config tại Tools > Sites > ContextHub
• Kiểm tra ContextHub store đã được load chưa trong browser DevTools > Application > localStorage
• Kiểm tra bundle com.adobe.granite.contexthub có Active không