Skip to main content

Troubleshooting guide

1. Core Requirements

  • Joomla Version: Joomla 4.0 or newer is required. The application relies on the native Joomla Web Services API.
  • PHP Version: PHP 8.1 or higher is recommended for optimal performance and security.
  • HTTPS/SSL: A valid SSL certificate is mandatory. For security, the iOS application will not communicate via unsecured HTTP.

2. Mandatory Native Configuration

  • SEF URLs: "Search Engine Friendly URLs" must be set to Yes in Joomla Global Configuration. The /api route will not function without this setting.
  • Native Web Services: In the Plugin Manager, ensure the following core "Web Services" plugins are enabled:
    • Web Services - Content (for articles and categories)
    • Web Services - Users (for user management)
    • Web Services - Menus (for menu items)

3. PHP Extensions & Media Manager

  • PHP Fileinfo Extension: This is mandatory. If fileinfo is disabled, Joomla cannot verify MIME types, causing errors in the Media Manager when listing or uploading files.
  • Memory Limit: Set memory_limit to at least 128MB (256MB recommended) to handle image processing.
  • Upload Limits: Ensure upload_max_filesize and post_max_size are sufficient for your media.

4. Authentication & Security Settings

  • Enable "Joomla Token": Ensure the plugin API Authentication - Joomla Token is enabled. This is the primary method used by the app.
  • Disable "Basic Auth": It is highly recommended to **disable** the plugin API Authentication - Web Services Basic Auth. Having both enabled can cause authorization conflicts (401 errors) on many servers.

5. Common Issues & Solutions

Internal Server Error (500)

  • Cause: Missing PHP extensions (like fileinfo) or insufficient memory.
  • Solution: Check server logs and ensure all required PHP modules are active.

API Error (404) - Resource Not Found

  • Cause: SEF URLs are disabled or a .htaccess file is missing.
  • Solution: Enable SEF URLs and ensure the default Joomla .htaccess is present.

Authorization Failed (401/403)

  • Cause: Invalid API Token or conflict with Basic Auth plugin.
  • Solution: Generate a new token for a Super User and ensure the Basic Auth plugin is disabled.

Firewall & Security Blocks

  • Issue: Actions like Saving or Deleting are blocked.
  • Cause: Web Application Firewalls (ModSecurity, BitNinja) blocking PATCH or DELETE methods.
  • Solution: Whitelist the /api/ path via your hosting provider.