Skip to content

Common Issues and Solutions

This page covers issues and their solutions across all AltText.ai integrations.

Access and Security Issues

403 Forbidden Errors

If you see 403 or "access denied" errors, this is typically caused by security tools blocking our image crawler.

Quick Fix:

  • Whitelist our User-Agent: AltTextAI/1.0.1 in your security settings
  • For CloudFlare: Go to Security → WAF → Create exception rule for User-Agent containing "AltTextAI/1.0.1"
  • For Wordfence: Go to Firewall → Blocking → Add User-Agent whitelist rule
  • For other security plugins: Add "AltTextAI/1.0.1" to your allowed user agents list

Additional Information: - Our crawler uses User-Agent: AltTextAI/1.0.1 for all image requests - We operate from Amazon CloudFront IP ranges for reliable access - We only access images that customers explicitly submit for processing - Full technical details available in our Bot Policy

CloudFlare Blocking Issues

CloudFlare's "Bot Fight Mode" and AI bot blocking features may block our crawler.

Solution:

  1. Log into your CloudFlare dashboard
  2. Go to Security → WAF → Custom rules
  3. Click Create rule
  4. Set the rule name: "Allow AltText.ai Crawler"
  5. Configure the rule:
  6. Field: HTTP User Agent
  7. Operator: contains
  8. Value: AltTextAI/1.0.1
  9. Action: Allow
  10. Click Save

This will allow our crawler to access your images while maintaining your site's security.

Processing Status Issues

"Processing Completed" but Alt Text Not Appearing

Image processing and alt text delivery are separate processes.

What this means:

  • Your images were successfully processed and alt text was generated
  • The notification or delivery system may have failed
  • Always check the actual status rather than relying on notifications

How to verify actual completion:

For Shopify: - Check the History area in your Shopify app - Look for your processed images and generated alt text there - If images appear in History, processing was successful

For WordPress: - Go to AltText.ai → History in your WordPress admin - Review the list of processed images - Check individual images in your Media Library for the alt text

For All Platforms: - Log into your AltText.ai dashboard - Review your recent processing activity - This shows the true status regardless of notification issues

Bulk Processing "Stuck" or Stopped

When bulk processing appears to stop partway through:

  • Check actual completion status (see above) - processing may be complete despite appearance
  • For WordPress: Large batches may timeout on shared hosting - try smaller batches
  • For Shopify: Bulk updates process slowly (1-2 images per second) due to Shopify rate limits
  • Wait for email notifications if enabled - processing continues in background

Credit and Billing Issues

Credits Deducted But No Results

If credits were used but you don't see results:

  • First, verify processing actually failed using the steps above
  • Check if images already had alt text (we skip those by default in most integrations)
  • Verify images met our requirements (min 50x50px, max 16MB, supported formats: JPG, PNG, WebP, GIF, BMP, AVIF, SVG)
  • Contact support if processing genuinely failed after verification

AppSumo Credits Not Appearing

See our AppSumo documentation for activation troubleshooting.

Integration-Specific Issues

Shopify: "History Area" Empty Despite Processing

  • History only shows product images that were processed
  • Blog/theme images don't appear in History but are still processed
  • Check your AltText.ai dashboard for all processed images

WordPress: "Plugin Crashes During Bulk Processing"

  • Disable metadata generation: In Technical Settings, uncheck "Allow WordPress to generate missing metadata"
  • Check hosting limits: Contact your hosting provider about memory/timeout limits
  • Process smaller batches: Use Media Library bulk actions instead of processing entire library
  • Verify "Public Internet" setting: Critical for proper image access

InstantAlt: Site Status Shows "Pending"

See our InstantAlt documentation for detailed explanation of pending status and how to resolve it.

BigCommerce: Alt Text Not Applying to Products

  • Check store permissions: Ensure the app has product management permissions
  • Verify webhook status: Check that BigCommerce webhooks are properly configured
  • Review bulk processing: Large catalogs may take time - check your dashboard for progress

Magento: Extension Not Processing Images

  • Verify OAuth integration: Check that the integration is activated in System → Integrations
  • Check API key validity: Ensure your API key has available credits
  • Cron job configuration: Verify Magento's cron jobs are running for background processing

Browser Extension: Not Working on Websites

  • Check extension permissions: Ensure the extension has permission to access the website
  • Clear extension data: Reset the extension data in browser settings
  • Website compatibility: Some sites with strict CSP policies may block the extension

Browser and Network Issues

Images Not Loading in Dashboard or History

  • Disable ad blockers temporarily - they may block our image URLs
  • Check browser console for JavaScript errors (F12 → Console tab)
  • Try a different browser to rule out browser-specific issues
  • Clear browser cache and cookies for the alttext.ai domain

Slow Processing Times

Processing speed varies based on: - Image complexity: Detailed images take longer than simple ones - Server load: Processing may be slower during peak usage times - Integration limits: Shopify (1-2/sec), WordPress (depends on hosting) - Image size: Larger images require more processing time

Expected processing times: - Simple images: 2-5 seconds - Complex images/advanced formats: 5-10 seconds - Bulk operations: 1-2 images per second (depending on platform limits)

Getting Additional Help

If these solutions don't resolve your issue:

  • Check our Bot Policy for technical details: alttext.ai/bot-policy
  • Contact support through the chat widget on alttext.ai
  • Include specific details:
  • Which integration you're using (WordPress, Shopify, etc.)
  • Exact error messages you're seeing
  • Steps you've already tried
  • Screenshots if applicable

Before contacting support, verify the actual processing status using the methods above - this resolves most reported issues.

Account and API Issues

Login Problems

  • Password reset: Use the "Forgot Password" link on the login page
  • Google OAuth issues: Try logging in with email/password instead, or clear browser data for Google
  • Account locked: Contact support if you see repeated login failure messages

API Error Responses

Common API error responses and solutions: - 403 Forbidden: Invalid or missing API key - check your X-API-Key header - 400 Bad Request: Invalid parameters or malformed request data

Alt Text Quality Issues

If generated alt text doesn't meet your expectations: - Add SEO keywords: Use keyword settings to influence content - Try different language settings: Some languages produce better results for specific content - Use custom prompts: Available in premium plans for more control - Image quality: Higher resolution images typically produce better alt text

Email Notifications Not Working

  • Check spam folder: Notification emails may be filtered
  • Verify email settings: Ensure notifications are enabled in account settings
  • Email delivery issues: Try adding noreply@alttext.ai to your contacts
  • Bulk processing notifications: Large operations may have delayed notifications