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.

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 in the UI by MelisCorePhpWarningListener. Error reporting/display can additionally be driven by Melis config under /meliscore/datas/errors.

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.

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 visible / "You don't have access to this tool"

Cause	Fix
User lacks rights	The left menu is gated by melis_core_user.usr_rights (XML allow-list). Grant the tool's *_toolstree_section via Access management, or 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.

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.

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).

Translations show the raw tr_… key

Cause	Fix
Locale not set	The active locale comes from the session (melis-lang-locale).
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 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
Flyway config	flyway/conf/flyway.conf, migrations in flyway/sql/