> For AI agents: the complete documentation index is available at https://nhanbe.id.vn/llms.txt, the full documentation bundle is available at https://nhanbe.id.vn/llms-full.txt.

# 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`:

```bash
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)`

```java
@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](https://experienceleague.adobe.com/docs/experience-manager-65/content/implementing/deploying/configuring/configuring-osgi.html)

***

#### 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