Common Issues

This page covers frequently encountered problems organized by category. Each entry follows the format: Problem, Cause, Solution.

Installation

Plugin fails to activate

Problem: Activating the plugin produces a fatal error or white screen.

Cause: PHP version is below 8.4, or a required PHP extension is missing.

Solution: Verify your PHP version meets the minimum requirement (8.4+). Ensure the following extensions are enabled: json, mbstring, openssl, curl, soap (required for ISSNet integration). Check your hosting control panel or run php -v and php -m from the command line.

WooCommerce not detected

Problem: Admin notice says "MIDDAG Account requires WooCommerce."

Cause: WooCommerce is not installed, not activated, or its version is below 9.0.

Solution: Install and activate WooCommerce 9.0 or later. MIDDAG Account checks for WooCommerce on plugins_loaded and will not fully initialize without it.

Composer autoloader not found

Problem: Fatal error referencing vendor/autoload.php.

Cause: Dependencies were not installed, or the vendor/ directory was deleted.

Solution: Run composer install --no-dev in the plugin directory. If deploying from a build archive, ensure you used composer dist:build which bundles dependencies.

Styles and scripts not loading

Problem: The admin UI appears unstyled or shows a blank page.

Cause: The Vite build output is missing from assets/dist/.

Solution: Run composer ui:npm:build to compile the React frontend. Verify that assets/dist/app.js exists after the build completes.

Configuration

Entitlements not created on purchase

Problem: A WooCommerce order completes but no entitlement appears.

Cause: The WooCommerce product is not mapped to an entitlement class, or the order status did not reach a completed state.

Solution: Edit the WooCommerce product and ensure the entitlement class field is set. Verify the order status reaches "completed" or "processing" (depending on your payment gateway). Check the plugin logs for errors during the order hook.

Organization boundary errors

Problem: API requests return AUTHORIZATION_ERROR with "organization mismatch."

Cause: The X-Middag-Organization header is missing or does not match the authenticated user's organization.

Solution: Include the X-Middag-Organization header in every API request. The value must be an organization ID where the authenticated user is an active collaborator. See Error Reference for specific error codes.

Policy engine not applying overrides

Problem: A per-organization or per-product policy override has no effect.

Cause: Policy overrides are evaluated in priority order: entitlement > product > organization > class > global. A higher-priority policy may be overriding your setting.

Solution: Check for policies at all five levels. Use the REST API to list active policies for the affected entitlement and verify the inheritance chain. The most specific policy wins.

JWT authentication fails

Problem: API requests with a JWT token return AUTHENTICATION_ERROR.

Cause: The token is expired, the signing key has changed, or the token was issued for a different site.

Solution: Request a fresh token. Verify the JWT private key file exists and is readable by the web server (but not in the webroot). Check that the server clock is accurate, as JWT validation is time-sensitive. See error codes MIDDAG-AUTH-TOKEN_EXPIRED and MIDDAG-AUTH-TOKEN_REVOKED in Error Reference.

Custom capabilities not working

Problem: A user with the expected role cannot access certain features.

Cause: Custom capabilities were not flushed after plugin activation, or a conflicting plugin is filtering capabilities.

Solution: Deactivate and reactivate the plugin to trigger capability registration. If the problem persists, check for other plugins that modify user_has_cap or use members/role-editor plugins that may strip custom capabilities.

Integrations

Stripe webhooks not arriving

Problem: Payments process in Stripe but the plugin does not update entitlement status.

Cause: The webhook endpoint URL is incorrect, Stripe is sending to the wrong environment, or the webhook secret is misconfigured.

Solution: In Stripe Dashboard, verify the webhook endpoint URL points to your site's REST API: https://yoursite.com/wp-json/middag-account/v1/webhooks/stripe. Confirm the signing secret in the plugin settings matches the one shown in Stripe. Check your server's error log for signature validation failures.

HubSpot sync errors

Problem: Organizations or deals are not syncing from HubSpot.

Cause: API credentials are expired, the HubSpot app scope is insufficient, or the dual-account configuration is pointing to the wrong portal.

Solution: Verify your HubSpot API key or OAuth token is valid. Ensure the app has the required scopes (contacts, deals, companies). For dual-account setups, confirm each account (BR and US) has its own credentials configured in the appropriate settings section.

ISSNet NFSe generation fails

Problem: Tax invoice generation returns an error or times out.

Cause: The SOAP endpoint is unreachable, the municipal certificate is expired, or required fields are missing.

Solution: Verify network connectivity to the ISSNet SOAP endpoint. Check that the digital certificate is valid and properly configured. Ensure all required fields (CNPJ, municipal registration, service code) are filled in the organization settings. ISSNet is specific to Brasilia/DF; other municipalities are not supported.

Banco Inter Pix/Boleto not generating

Problem: Payment slips or Pix codes are not created.

Cause: The Banco Inter API credentials or certificate are invalid, or the webhook callback URL is unreachable.

Solution: Verify the client ID, client secret, and mutual TLS certificate in the plugin settings. Ensure your server can reach Banco Inter's API endpoints. Check that the webhook callback URL is publicly accessible (not behind basic auth or IP restrictions).

Jira service request sync stalls

Problem: Service requests created in MIDDAG Account do not appear in Jira, or updates from Jira do not sync back.

Cause: The Jira API token is expired, the project key is wrong, or field mappings are misconfigured.

Solution: Verify the Jira API token and base URL in plugin settings. Confirm the target Jira project exists and the token has permission to create and update issues. Check the field mapping configuration to ensure MIDDAG Account fields correspond to valid Jira custom fields.

Getting More Help

If your issue is not listed here, see:

• Error Reference for specific error codes and fixes
• Support for how to report bugs and get assistance