jmiller
b9bf7750dd
Updated version in all .ini, .php, .md files to 02.01.08. Added SHA256 checksum to updates.xml for install integrity validation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
4.9 KiB
MokoWaaS Troubleshooting Guide (VERSION: 02.01.08)
Introduction
The MokoWaaS Troubleshooting Guide provides a structured, repeatable approach for diagnosing and resolving issues related to branding enforcement across WaaS managed Joomla environments. It assists administrators, support engineers, and operations staff in identifying symptoms, validating root causes, and restoring consistent platform behavior.
This guide focuses on actionable diagnostics, minimizing downtime, and ensuring that WaaS branding policy is applied consistently.
Understanding the Plugin’s Operational Behavior
As a system level extension, the MokoWaaS plugin:
- Loads early in the Joomla lifecycle
- Influences visible terminology and branding markers
- Interacts with templates, overrides, and language constants
- Depends on correct cache behavior and language file integrity
Issues typically arise from conflicts, outdated overrides, or environmental configuration rather than the plugin itself.
Common Issues and Resolutions
Branding Not Updating
Branding appears unchanged or reverts to Joomla defaults.
Likely Causes:
- Joomla cache not cleared
- Browser cache holding stale assets
- Template overrides overriding plugin output
- Language file conflicts or outdated strings
Resolution:
- Clear Joomla cache entirely.
- Test in a private browser session.
- Inspect template override directories for conflicting files.
- Confirm plugin is enabled.
- Validate plugin load order.
Missing or Incorrect Terminology
Labels or UI strings do not match expected WaaS terminology.
Likely Causes:
- Outdated or missing language packs
- Third party extensions overriding key strings
- Joomla updates introducing new terminology
Resolution:
- Validate the integrity of all language files.
- Check extension overrides.
- Reapply updated MokoWaaS language packs.
- Review recent Joomla updates for changes in language constants.
UI Rendering Issues
Visual inconsistencies or broken layouts.
Likely Causes:
- Template level CSS conflicts
- Third party system plugins modifying DOM or rendering pipelines
- Outdated or incompatible template overrides
Resolution:
- Switch temporarily to a default template.
- Inspect and test CSS priority.
- Disable third party plugins one at a time to isolate conflicts.
Diagnostic Tools and Logs
Effective diagnosis depends on reviewing the correct system logs.
Joomla Logs
Monitor for:
- Plugin initialization warnings
- Deprecated methods
- Handler conflicts between extensions
PHP Error Logs
Check for:
- Undefined constants or missing language keys
- Fatal or recoverable errors in plugin lifecycle hooks
Browser Developer Tools
Useful for detecting:
- JavaScript conflicts affecting admin UI
- Missing or misrouted asset loads
- DOM rendering issues
Escalation Workflow
If your troubleshooting steps do not resolve the issue:
-
Document observed symptoms and any steps already taken.
-
Capture relevant logs, console messages, and screenshots.
-
Escalate to WaaS operations or development teams.
-
Include environmental details such as:
- Joomla version
- MokoWaaS plugin version
- Template version
- Installed third party extensions
Preventative Practices
To reduce incidents and ensure operational stability:
- Maintain version alignment across templates, plugins, and language packs.
- Test all changes in a staging environment.
- Enforce change control for branding or terminology adjustments.
- Remove legacy template overrides that duplicate plugin functionality.
Revision History
| Date | Author | Description |
|---|---|---|
| 2025-12-11 | Jonathan Miller (@jmiller-moko) | Full rewrite and update to version 01.03.00 |