Troubleshooting & operations

A field guide to the problems you'll actually hit, with the cause and the fix. When something "doesn't show up", the answer is almost always modules / rights / cache.

In v6 the back-office is the React shell at /melis-react, but the framework, modules and config underneath are unchanged — so most fixes here are still server-side. Where a tool has no native React page, the shell renders the classic tool inside an iframe (/melis/react-tool-page?key=<melisKey>), and native-React "brick" tools carry a New (React) / Old (iframe) toggle to that same classic screen. Knowing which layer you're looking at is often the first diagnostic step.

Turn on errors first

By default Melis is quiet about errors. Enable development mode to see them:

vendor/bin/laminas-development-mode enable     # status | enable | disable

This loads config/development.config.php, disables config/module caches and sets error_reporting(E_ALL). PHP warnings are also surfaced by MelisCorePhpWarningListener. Error reporting/display can additionally be driven by Melis config under /meliscore/datas/errors.

Note that the React API endpoints answer JSON, not HTML: a failing boot call returns { success: false, error: … } (e.g. { success:false, error:'Unauthenticated' } with HTTP 401), so read the network tab, not just the page. A legacy tool inside the iframe still shows its own native errors (gritter toasts, per-field validation modals) exactly as under /melis.

Blank page, HTTP 200, no error?

Melis uses output buffering; a fatal during bootstrap/render can yield an empty 200. To see the swallowed exception, temporarily attach a listener to MvcEvent::EVENT_DISPATCH_ERROR / EVENT_RENDER_ERROR in public/index.php (wrap Application::init() in try/catch and print the exception param), or enable development mode.

Cache

Stale cache is the #1 cause of "I changed config but nothing changed". Caches live under cache/:

cache/meliscore_platform_cache-*   # backoffice zones / platform config
cache/meliscms_page-*              # rendered CMS pages
cache/config/                      # merged Laminas config (if enabled)

Clear them by deleting the relevant folders, or via the API MelisCoreCacheSystemService::deleteCacheByPrefix('*', 'meliscore_platform_cache'). Melis also clears caches automatically on module-management and rights changes. After editing config/melis.module.load.php or any app.*.php, clear cache/melis* and reload.

From the back-office you can clear caches from the Cache tool (its React screen carries the same tabs as the classic tool). See MelisCacheInternal.

The React shell has its own layer of caching to be aware of when things look stale:

• The concatenated bricks bundle (/melis/react-api/bricks-bundle.js?v=<sig>) is served 1-year immutable; its ?v= signature (name+mtime+size of every brick) changes automatically when a brick's files change, so a hard refresh picks up the new bundle.
• The SPA shell (index.html) is served no-cache, but the hashed JS/CSS assets it references are content-hashed and cached — again, a hard refresh is the cure.
• If a tool iframe loads with broken styling or an empty DataTable after a Modules change, the platform asset bundles under etc/bundles/ may have been wiped; they self-heal (regenerated on next tool-page render), but you can force it by reloading the tool.

Common pitfalls

A module doesn't appear

Cause	Fix
Not in the load list	Add it to config/melis.module.load.php.
Stale cache	Clear cache/melis* and reload.
Path not mapped	Ensure it's in the generated config/melis.modules.path.php (regenerated by MelisAssetManager).

A tool exists but isn't in the left menu / "You don't have access to this tool"

The React left menu (GET /melis/react-api/menu) is the rights-filtered nav tree — same melis_core_user.usr_rights XML allow-list as before, just consumed by the shell.

Cause	Fix
User lacks rights	Grant the tool's *_toolstree_section in Users → Rights, or via a migration (see flyway/sql/V3__add_melisai_rights.sql).
Rights cached in session	Rights are loaded at login and refreshed periodically by MelisCoreCheckUserRightsListener — log out / back in after changing them.
User inactive	usr_status must be 1.
Brick's module inactive	A native-React tool (brick) appears if and only if its module is active — the shell discovers bricks via GET /melis/react-api/react-modules. Enable the module.

An empty usr_rights means full access (isAccessible() returns true on empty) — but for a normal user with an explicit allow-list, a missing section is hidden.

A tool's button/tab is forbidden even though I can open the tool (HTTP 403)

v6 adds advanced rights ("capabilities") inside an already-authorised tool — the fine-grained List / Create / Edit / Delete / per-tab checkboxes in Users → Rights.

Cause	Fix
Capability denied	The tool's controller called denyUnlessCan(<cap>) and your rights XML denies that cap. Un-deny it in Users → Rights (advanced-rights matrix).
Cached in session	Capabilities arrive in the boot call GET /melis/react-api/me (data.capabilities) — log out / back in after editing rights.

Capabilities are default-allow: a tool with no declaration, or a cap that isn't denied, stays fully usable; admins bypass entirely. Denials live in a dedicated <meliscore_tool_capabilities> section of the rights XML, so they don't affect the classic BO.

A legacy tool loads empty / its buttons do nothing inside the React shell

When a tool has no native React page it renders in an iframe via /melis/react-tool-page?key=<melisKey>. An empty DataTable or a dead button there is almost always a missing module resource (its own *.tool.js/CSS not injected).

Cause	Fix
Module resource not loaded	The tool page injects each module's ressources; a newly-contributed tab/button that ships JS the page doesn't know about needs its plugin root registered (or a toolpage_extensions hook — see Create a tool).
Compare against /melis	Open the same tool directly at /melis (or via the tool's Old toggle). If it's broken there too, the problem is in the tool itself, not the React frame.

Database connection errors

Cause	Fix
Platform file missing	config/autoload/platforms/<MELIS_PLATFORM>.php must exist and match the MELIS_PLATFORM env var.
Wrong credentials	Check MYSQL_* env vars consumed by the platform file.

Assets (CSS/JS) 404

Cause	Fix
Module not mapped	Check config/melis.modules.path.php.
Bundles not built	Rebuild assets (Webpack build / vendor/bin/phing).
Stylesheet answered as HTML	An expired session used to redirect a bundle request to the HTML login page (browser rejects the MIME); v6 serves the platform bundle at /melis/react-platform-bundle with the correct type and keeps it public — a hard refresh clears the stale rejection.

Translations show the raw tr_… key

Cause	Fix
Locale not set	The active locale comes from the session (melis-lang-locale); the React header's language switcher writes it (GET /melis/react-api/langs).
File missing	Add language/<locale>.interface.php; en_EN is the fallback.

Database schema (dbdeploy & flyway)

• dbdeploy (MelisDbDeploy) runs on composer update (post-update hook) to apply each module's numbered SQL deltas, tracked in the changelog table.
• flyway (MelisFlyway) applies project migrations in flyway/sql/ (flyway -configFiles=flyway/conf/flyway.conf migrate).

CLI & build tools

vendor/bin/laminas-development-mode {status|enable|disable}   # dev mode
flyway -configFiles=flyway/conf/flyway.conf {migrate|info|repair}   # DB migrations
vendor/bin/phing                                             # build assets/bundles

composer update triggers Melis hooks (module deploy + dbdeploy) via composer.jsonpost-update-cmd.

Where to look

Concern	Path
Dev mode template	config/development.config.php.dist
Cache API	vendor/melisplatform/melis-core/src/Service/MelisCoreCacheSystemService.php
Rights refresh	vendor/melisplatform/melis-core/src/Listener/MelisCoreCheckUserRightsListener.php
PHP warnings	vendor/melisplatform/melis-core/src/Listener/MelisCorePhpWarningListener.php
Module assembly	vendor/melisplatform/melis-core/src/MelisModuleManager.php
React API (menu / me / capabilities)	vendor/melisplatform/melis-react-api/src/Controller/MelisReactApiController.php
React shell / iframe tool pages	vendor/melisplatform/melis-react-override/src/Controller/PluginViewController.php
Flyway config	flyway/conf/flyway.conf, migrations in flyway/sql/