Troubleshooting¶
Composer cannot authenticate or find Nebula packages¶
Complete the Nebula Admin checkout for €0.00 first. The free order is required before Composer access is issued. Key generation is queued and can take up to five minutes. Open My Account → Nebula Keys (free) in your qoliber account, refresh after the wait, and use the current key with composer.qoliber.com as shown on Install. If the key is still missing after five minutes, contact Support from your account with your order number.
Check that the repository URL is https://composer.qoliber.com/r/nebula and that authentication is configured for the user running Composer. Keep the key out of support messages and version control.
The admin throws "Nebula compiled manifest is missing"¶
You are in production mode and generated/nebula/definitions.php does not exist or lacks the definition named in the message. Run:
setup:di:compile writes the manifest as well, so a deploy that skips di:compile, or a generated/ directory that was cleaned after it ran, is the usual cause. See Caching and production mode.
A grid renders with no rows¶
The definition's dataSource.config.collection must be a registered alias, not a class name. Aliases are bound in di.xml on the collection registry. An unknown alias logs a warning in var/log/system.log and the grid shows no rows. Check that log and Data providers.
A grid or form shows "Access denied" or nothing at all¶
Every definition needs an acl key. The access control is default-deny: a definition with no acl is refused for every administrator. Add the resource id and grant it to the role.
A form renders twice, or the core form renders beside it¶
The route map is memoised per request and the generated layout is cached by handle. After adding or changing a route, replaces or routeWhen key, flush the layout cache:
Nebula adds the form id to the layout cache key, so two forms on one route stay apart, but a stale entry from before the change can survive until it is cleaned.
A definition change is not visible¶
In default mode the merged definition is cached under the nebula_definitions cache type. Clean it:
In production mode re-run nebula:compile. In developer mode definitions are read live on every request.
The page renders but a custom Alpine component does nothing¶
Open the browser console. If Alpine reports an expression error, the admin Content Security Policy is enforcing without 'unsafe-eval'. See Requirements. If there is no error, check that the page loads the bundle your component lives in:
An admin AJAX call fails with "Unexpected token '<' ... is not valid JSON"¶
Read the raw response body in the network tab before you look at the controller. If its first line is the comment <!-- NEBULA_ROOT_PHTML_MARKER -->, sitting above the doctype, the body is the admin HTML shell rather than JSON. That marker means the request never reached your controller. It never means a serialisation bug, because an endpoint that actually ran answers JSON, typically {"success": true, "data": ...}. The three causes are an unresolved route, a missing form key or secret key, and an expired admin session.
The first cause is a controller action added since the last cache clean. Outside production mode Magento loads the map of full action names to classes from the config cache and rebuilds it from the filesystem only when that cache is empty, so developer mode does not help. The unresolved route falls through to the admin's own 404 handling, which answers with the shell under a 404 status. Clean the cache:
The second cause is a request that carries no admin form key or secret key. Magento validates the form key on every admin POST, and the secret key on other requests when secret keys are enabled. On failure it abandons the dispatch and redirects to the admin startup page. fetch follows that redirect, so the client sees a 200 and an HTML page. Put the form key and the isAjax flag on the URL, taking the key from $block->getFormKey() in the template that renders your script:
Magento answers a key failure with JSON only when isAjax is present in the query string. Sending isAjax in the POST body does not work.
The third cause is an admin session that has expired. A request from a signed-out administrator is forwarded to adminhtml/auth/login, which renders the same shell and the same marker, so a call that worked an hour ago can start returning HTML with no code change. Sign in again in another tab and retry. isAjax on the query string prevents this too: with it the request is forwarded to adminhtml/auth/deniedJson, which answers {"ajaxExpired": 1, "ajaxRedirect": "..."} and lets your client detect the timeout.
A third-party admin screen looks unstyled¶
Magento's convention is LESS at view/adminhtml/web/css/source/_module.less, compiled by the Magento/backend theme. Nebula has no parent theme and compiles nobody's LESS, so a module that styles its admin UI that way arrives with markup and no stylesheet. The fix is on the module's side: a plain CSS file over Nebula's --nebula-* tokens, loaded from layout XML. See CSS and JavaScript in your module.
A third-party UI Component grid renders as an empty shell¶
There is no Knockout runtime under Nebula. A <uiComponent> that Nebula does not replace is still read from layout and its container renders, but the JavaScript that fills it never runs. Options: convert the XML with nebula:ui:transform, or enable the UI Bridge, included with nebula/admin, which converts supported components at runtime.
I am locked out after enabling two-step¶
bin/magento security:tfa:reset <admin username> nebula_passkey
bin/magento security:tfa:reset <admin username> google
Then sign in again. nebula:passkey:reset-two-step --user=<admin username> resets Nebula's own two-step verification instead, and is the command only where Magento_TwoFactorAuth is disabled.
Getting help¶
Run bin/magento nebula:doctor and send its output to the distributor who issued your licence, along with the Magento or Mage-OS version, PHP version, deploy mode, browser, and the enabled module list.