Reference

Troubleshooting

Common Kestros symptoms and how to fix them, grouped by where they show up. Each entry states what you see, why it happens, and the fix. Several of these failures are quiet: the build reports success or the page still renders, so the only clue is that nothing looks right. Start with the group that matches your symptom.

Build & deploy

Build succeeds but nothing is deployed

Symptom. mvn clean install reports BUILD SUCCESS, but the instance shows none of your bundles or content.

Cause. A plain build only compiles and packages. Deployment is opt-in through Maven profiles, so without them nothing is pushed to the running instance.

Fix. Activate the install profiles: mvn clean install -PinstallBundle,installPackage,installContent. installBundle deploys OSGi bundles, installPackage / installContent install content packages.

Content is missing right after BUILD SUCCESS

Symptom. The build succeeds, but the pages or nodes you just deployed are not on the instance the instant it finishes.

Cause. Content-package installs are asynchronous. A success only means the package was uploaded and the import job was queued; the actual import runs a moment later on a background thread.

Fix. Wait a few seconds after the build reports success, then re-check that the content exists. Do not treat the instant of BUILD SUCCESS as proof the import finished.

Each package install hangs for minutes

Symptom. Every content-package install stalls for a long time (up to several minutes) before proceeding.

Cause. Before importing a package, the build waits for every bundle to become Active. If a bundle is stuck (for example in Installed), that full wait is paid on each install.

Fix. First make sure your bundles reach Active (a bundle stuck in Installed or Resolved is a real problem to chase). To skip the wait during iteration, pass -Dvault.bundleStatusWaitLimit=1 to cap the wait at one second.

Rendering

A heading renders blank

Symptom. A heading component produces an empty element: no text, no error.

Cause. The heading component reads headingText and headingType. Other property names such as text or level are ignored silently.

Fix. Author the heading with headingText and headingType. When a heading comes out blank, check the property names first.

A component uses the wrong layout, quietly

Symptom. A component renders with the default layout even though you named a different one. No error appears.

Cause. An unknown layout name fails silently. When the named layout does not exist on the resolved component view, resolution falls back to default and the caught error is not surfaced, so a typo is easy to miss.

Fix. Confirm the layout name exists on the component view you expect to resolve. Check for typos and for a layout that was never added to that view.

Empty-include error when no layout is named

Symptom. A component fails at render time with Sling reporting Path for data-sly-include is empty.

Cause. The component view offers named layouts but no default, and the request did not name a layout, so nothing resolves to include.

Fix. Give every component view a default layout so an unnamed request always has something to render.

A variation does not apply, or the wrong one does

Symptom. The variation you referenced does not take effect, even though its display title looks correct.

Cause. A variation is matched by its node name, not its jcr:title. variations="[bg-primary]" resolves the variation whose node name is bg-primary; the jcr:title (“Primary”) is display-only.

Fix. Reference variations by node name. When auditing applied-versus-registered variations, compare node names, not titles.

A variation class never lands on the element

Symptom. A variation is applied, but its CSS class does not appear in the rendered markup.

Cause. The variation is marked inline="true". An inline variation is not added to the component's wrapper element automatically; the component's own HTL must emit it. The default (inline="false") is what adds the class to the wrapper for you.

Fix. For an inline variation, print ${component.inlineVariations} on the element that should receive the class in the component's layout markup. Otherwise set the variation to non-inline so Kestros adds it to the wrapper.

Frameworks & libraries

Pages render unstyled and the theme CSS request returns 400

Symptom. Pages come out unstyled, with no error on the page itself. The request for the compiled theme CSS returns HTTP 400 with the message Failed to retrieve UiFramework.

Cause. A uiFrameworkCode mismatch. For a managed framework the code is read from the root node; a kes:uiFrameworkCode on a version node is ignored. If the root code does not match how the framework is referenced, the theme CSS lookup fails.

Fix. Keep the framework's root uiFrameworkCode equal to the folder name and to however the framework is referenced. Setting the code only on a version node does not help.

Pages 500 with "Failed to include script" after a component-view package install

Symptom. Right after installing a package that ships component views, rendered pages return a transient HTTP 500 with Failed to include script. The build itself reported success.

Cause. Installing a FileVault package replaces the content inside its filter roots: nodes removed from the package are removed from the instance for any path the filter covers, while paths outside the filter includes are merged rather than replaced. When that install changes component-view trees, the component-view cache can be left stale for a moment, and pages fail to include the expected script until it settles.

Fix. Redeploy kestros-site-building-core and let it settle to clear the stale component-view cache. Confirm your filter.xml roots cover exactly the view trees you intend to replace, so the install does not drop nodes you meant to keep.

Authoring & dialogs

Dialog fields do not bind (legacy dialog format)

Symptom. A dialog's fields do not read or write the properties you expect.

Cause. The dialog is built on the legacy kestros/cms/dialog format, which used a different field vocabulary: fields addressed the property with propertyName= rather than name=.

Fix. Build new dialogs on sling:resourceType="kestros/cms2/dialog" and address properties with name=. A running instance still carries both /libs/kestros/cms/* and /libs/kestros/cms2/*, but cms2 is the supported shape.

A component's type is lost after deploy (docview delivery)

Symptom. A custom component's nodes land as sling:Folder and the kes:ComponentType is gone, so the component is not recognized.

Cause. The docview .content.xml was delivered through Sling-Initial-Content. The bundle content loader expects .json node definitions, so docview XML loaded that way is misread as plain folders.

Fix. Ship docview content through a content package (installPackage) and ship Java through the bundle (installBundle). Do not deliver docview via Sling-Initial-Content.

A template disappears after a rebuild

Symptom. A page template you created in the running instance is gone after the instance is rebuilt.

Cause. Templates created that way are not stored in code, so a rebuild does not restore them.

Fix. To keep a template, create and download a content package, then extract it into your project source so it is rebuilt with the rest of the project.

A page ignores its template (page template vs site template)

Symptom. Setting a template value on a page does not give it the template you intended.

Cause. Two different template concepts are easy to confuse. A page selects its per-page template through kes:template, which must point at a kes:PageTemplate. A kes:SiteTemplate is a separate node type used to create a whole site, not the per-page value.

Fix. Point kes:template at a kes:PageTemplate node. Use kes:SiteTemplate only for site creation.

Datasources

Datasource nodes 404 even though the build succeeded

Symptom. A datasource registration overlay builds and installs with success, but the node returns a 404 at runtime.

Cause. The FileVault intermediate-folder gotcha. When you ship the overlay as a FileVault content package under the out-of-the-box /apps/kestros/commons/components tree and cover only the leaf node, FileVault skips the intermediate folders it does not know about, so the build reports success while the node never installs.

Fix. Ship a sling:Folder .content.xml for every intermediate folder your overlay introduces, and list those ancestor paths in filter.xml as explicit <include> patterns. Alternatively, deliver the nodes as bundle initial content, which avoids the FileVault packaging step entirely.