Vexal Media Troubleshooting

Common Vexal Media issues and how to resolve them.

Upload too large

• Check PHP upload_max_filesize and post_max_size in server config
• Check WordPress max upload size in Site Health → Info
• Nginx/Apache may have separate body size limits
• For video, use Vexal Media Videos admin rather than raw Media Library for large masters

Server returns HTML instead of JSON

• Usually a PHP fatal error, security plugin block, or redirect to login page
• Open browser Network tab on the failing AJAX request—response body often shows the error
• Disable other plugins temporarily to isolate conflicts
• Verify REST/AJAX URL is correct and not cached by CDN
• Check .htaccess or WAF rules blocking admin-ajax.php

413 errors

HTTP 413 Payload Too Large—server or proxy rejected the upload before WordPress processed it.

• Increase nginx client_max_body_size or Apache LimitRequestBody
• Check Cloudflare or CDN upload limits
• Reduce file size or compress before upload

Missing alt fix does not run

• Verify Vexal/SearchAsist Engine credentials if using AI alt generation
• Batch limit is 50 items—large libraries need multiple runs
• Check processing queue for stuck items in Vexal Media admin
• Some attachments may be excluded (SVG, non-image types)
• Review logs for API rate limits or timeout errors

WebP conversion unavailable

• Requires PHP imagewebp function—check with function_exists('imagewebp')
• GD or Imagick must support WebP on your server
• Readiness panel shows webp_available status
• Contact host to enable WebP support if missing

Video optimizer unavailable

• Remote optimization requires API credentials in Vexal Media settings
• Local FFmpeg fallback needs FFmpeg installed on server PATH
• Check Videos admin for per-video error messages
• Large masters may timeout—increase PHP max_execution_time

API / proxy not configured

• Configure credentials in Vexal Media → Settings / Integrations
• Can inherit from SmartBlocks Integrations when both plugins active
• Do not configure APIs in Portfolio Project Workspace
• Verify outbound HTTPS to api.vexalai.com is not blocked by firewall
• Proxy settings must allow WordPress HTTP API requests

Broken image URLs after rename/WebP

Vexal Media includes URL scan/repair after rename and WebP conversion. Run repair from Media admin if content still references old filenames.