Skip to main content

​
WooCommerce not active

Symptom: An admin notice appears: “UTB Product Builder requiere que WooCommerce esté instalado y activo.” All plugin functionality is disabled. Resolution:
  1. Verify WooCommerce is installed: Plugins → Installed Plugins.
  2. Activate WooCommerce if it is installed but inactive.
  3. If WooCommerce is not installed, go to Plugins → Add New and search for WooCommerce.
  4. After activating WooCommerce, reload any admin page — the notice should disappear and the plugin initializes.

​
Fatal error monitor

The plugin registers a PHP shutdown function that catches fatal errors and writes them to the WooCommerce log under the source utb_fatal_monitor: 
🚨 FATAL ERROR CAUGHT: Array ( [type] => 1 [message] => ... [file] => ... [line] => ... )
To view these logs: WooCommerce → Status → Logs. Select the log file with suffix utb_fatal_monitor-YYYY-MM-DD from the dropdown.

​
Debug mode activation

Add #debug or ?debug=1 to the URL of any CEP or Certificates product page to enable verbose AJAX logging in the browser console.
Debug mode requires the current WordPress user to have the Administrator (manage_options) or Editor (edit_posts) role. Anonymous users and subscribers are silently blocked — the URL parameter is ignored without error.
The backend sets UTB_CEP.debug_allowed in the localized JS object based on current_user_can('manage_options') || current_user_can('edit_posts'). The frontend cep-debug.js reads this flag before activating. You can also enable debug from the browser console while logged in: 
window.UTB_DEBUG.enable();
This prints the full AJAX request/response waterfall for each discount or price check in the Chrome DevTools console.

​
Form fields not showing

Symptom: The enrollment or certificate form renders with missing fields or sections. Possible causes and fixes:
FormConfigManager::get_config() returns null if the product has no _utb_form_config meta, no _utb_linked_cert_id meta, and the flow’s get_default_config() is empty.Fix: In the WordPress admin, go to the product edit page and use UTB Builder → Form Builder to assign and save a configuration, or run wp eval-file migrate-flows.php to write the default config to the product meta.
If the JSON in _utb_form_config is malformed, json_decode() returns null and the form falls back to the hardcoded default (which may differ from what was expected).Fix: Retrieve the meta value and validate it:
wp post meta get {product_id} _utb_form_config | python3 -m json.tool
Correct any syntax errors or re-save from the Form Builder.
Fields with start_hidden: true (such as utb_qty) rely on JavaScript events to show. If a prior JavaScript error aborts execution, the show/hide logic never runs.Fix: Open the browser console, enable debug mode, and check for JS errors. Ensure no theme or third-party plugin script conflicts with certificados-flow.js.

​
Price not updating in CEP

Symptom: After selecting a CEP program, the price label below the dropdown does not appear. Cause: jQuery animation methods (.slideDown(), .show()) leave residual inline styles (visibility: hidden, height: 0px) that block visibility. This was fixed in v2.4.2.5. Diagnosis: Inspect the #cep_program_price_label element in browser DevTools. If it has style="visibility: hidden" or height: 0, the animation conflict is occurring. Fix (v2.4.2.5 and later): cep-flow.js uses direct style assignment with !important to override any jQuery-set values: 
// Instead of .slideDown():
$('#cep_program_price_label').attr('style', 'display:block !important; visibility:visible !important;');
If you are on an earlier version, upgrade the plugin. If the problem persists after upgrading, check that a theme’s global CSS is not setting visibility: hidden on .cep-program-price elements. Additional fix for selector conflicts (v2.4.2): If the program selector does not fire the change event at all, verify that cep-flow.js uses .off('change').on('change', ...) to prevent duplicate event handlers registered by theme scripts.

​
Webhook failures

Symptom: Orders complete but the downstream system does not receive notifications. Diagnosis:
  1. Go to WooCommerce → Status → Logs and select a utb_product_builder-YYYY-MM-DD log file.
  2. Look for [error] Webhook Sender entries showing the HTTP status code and response body from the target URL.
  3. Check wp_utb_webhook_logs directly: 
    SELECT * FROM wp_utb_webhook_logs ORDER BY created_at DESC LIMIT 20;
Retry logic: The webhook sender retries failed deliveries up to 3 times with delays of 5 seconds, 15 seconds, and 60 seconds using wp_schedule_single_event. If all retries fail, the status column in wp_utb_webhook_logs is set to failed. Signature validation: Outbound webhooks include an HMAC signature header. Ensure the receiving system validates against UTB_WEBHOOK_SECRET (or wp_salt('auth') if the constant is not defined).

​
AJAX nonce errors

Symptom: AJAX calls return {"success":false,"data":{"message":"La sesión ha expirado o la petición no es válida."}} with error code security_check_failed. Causes:
  • The page was cached and served with a stale nonce (nonces expire after 12 hours by default).
  • A caching plugin (WP Rocket, W3 Total Cache, etc.) cached the product page including the localized UTB_CEP JavaScript object with an old nonce.
Fix:
  1. Exclude WooCommerce product pages from page caching in your caching plugin’s settings.
  2. Alternatively, configure the caching plugin to strip the UTB_CEP JS variable from cached output.
  3. If using a CDN, ensure product pages are not edge-cached.

​
Nginx: REST API returning 404

Symptom: GET /wp-json/utb/v1/orders returns a 404 or an HTML Nginx error page instead of JSON. Cause: The Nginx configuration is missing the mod_rewrite equivalent (try_files) rule that routes all requests through WordPress. Fix: Ensure your Nginx site block contains: 
location / {
    try_files $uri $uri/ /index.php?$args;
}
Also verify the REST API is not blocked by a deny all rule before the location / block. This was documented as a critical fix in v2.4.0 (the Apache .htaccess equivalent is the RewriteRule .* - [E=HTTP_AUTHORIZATION:%{HTTP:Authorization}] line). After editing the Nginx config: 
sudo nginx -t && sudo systemctl reload nginx

​
Log locations

LogLocationControlled by
API access logWP_CONTENT_DIR/utb-api-access.logUTB_API_LOGGING = true
Failed auth logWP_CONTENT_DIR/utb-api-failed-auth.logUTB_API_LOGGING = true
WooCommerce generalWooCommerce → Status → Logs (utb_product_builder-*)WC logger
Fatal error monitorWooCommerce → Status → Logs (utb_fatal_monitor-*)Shutdown function in Plugin.php
CEP discount/rolesWooCommerce → Status → Logs (cep-discount-*, cep-roles-*)CEPDiscountCalculator::log(), CEPRolesValidator::log()
Symptom: Users report “Hubo un problema de conexión al validar” or discount check hangs. Diagnosis steps:
  1. Check the cep-roles log source in WooCommerce Status → Logs for [error] HTTP ERROR entries.
  2. Send a test request from the server: 
    curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer {token}" \
  "{api_base}/woocommerce/rol?documento=12345678"
    If this returns HTML (Microsoft Entra SSO redirect), the firewall or SSO interceptor is active.
  3. Verify Banner API response keys are still uppercase. The validator expects NOMBRE, APELLIDOS, IDENTIFICACION, and ROLES. If the ERP response mutated key casing, fix the mapping in CEPRolesValidator.php at the point where $data['NOMBRE'] and $data['APELLIDOS'] are read (lines 126–128).

Build docs developers (and LLMs) love

Get started for freeTalk to us