Skip to main content

Troubleshooting

This comprehensive troubleshooting guide provides solutions to common problems you might encounter while using the BILDIT Web Visual Experience Engine.

Authentication Issues​

Login Problems​

Invalid Credentials​

Problem: Unable to log in with username and password

Solutions:

  • Double-check your username and password for accuracy
  • Ensure that Caps Lock is not enabled on your keyboard
  • If you've forgotten your password, use the "Forgot Password" link to reset it
  • Contact support if the issue persists

Account Locked​

Problem: Account locked after multiple failed login attempts

Solutions:

  • After multiple failed login attempts, your account may be locked for security reasons
  • Wait for 15 minutes before trying again
  • Reach out to support to unlock your account immediately

Two-Factor Authentication (2FA) Issues​

Problem: Unable to complete 2FA verification

Solutions:

  • Ensure your authenticator app is synced correctly
  • Check that your mobile device's time settings are accurate
  • Use backup codes if available
  • Contact support for assistance

Visual Editor Script Issues​

These cover the Visual Editor script for editing in the Visual Editor. Production-site rendering is handled by the SDK — see Scheduled Content Not Showing on Your Production Site.

Editor Script Not Loading​

JavaScript Errors​

Problem: Console shows JavaScript errors preventing Visual Experience Engine from loading

Solutions:

  • Open your browser's console to check for any JavaScript errors
  • Common errors include syntax errors or conflicts with other scripts
  • Resolve any errors indicated in the console
  • Check for conflicting JavaScript libraries

Scheduled Content Display Issues​

First, where is the scheduled content missing?

Scheduled Content Not Showing on Your Production Site​

Your production site renders via the @bildit-platform/nextjs SDK. Check, in order:

  1. Free-trial plan — free_sandbox is blocked on production by design (401); upgrade the plan to serve (the same key works).
  2. Scheduled content location — must match the page path, or the SDK returns nothing.
  3. BILDIT_API_URL — must be the root URL of the CMS instance that holds your data (the host you log into BILDIT at — a sandbox uses https://<your-site>.web.app, not the shared admin.bildit.co); the SDK appends /remote-webbanners_v1_4. Wrong host → Invalid API Key / blank site.
  4. force-dynamic — required in your root layout so headers are read per request.
  5. Env vars in production — are BILDIT_API_KEY and BILDIT_API_URL set in your host's environment (not just locally)? Missing in prod → nothing renders.
  6. cmsDependencies — an unregistered module scheduled content imports throws a render error.
  7. Caching — the SDK caches ~5 minutes; wait or redeploy after changes.

Full checklist: API Reference & Troubleshooting.

Scheduled Content Not Showing Up (Visual Editor)​

Schedule Not Active​

Problem: Scheduled content is created but not displaying on the website

Solutions:

  • Verify that the schedule is currently active
  • Check the "Online From" and "Online To" dates using date simulation
  • Ensure current date/time falls within the scheduled period

Slot Mismatch​

Problem: Scheduled content appears in wrong location or not at all

Solutions:

  • Ensure the slot id matches the Slot assigned to your scheduled content — the slotId on your <SlotPlaceholder>.
  • Example: <SlotPlaceholder slotId="slot1" />
  • Check for typos in slot identifiers

Device Type Not Selected​

Problem: Scheduled content doesn't appear on certain devices

Solutions:

  • Confirm that the scheduled content is set to display on the device you're using (Desktop, Tablet, Mobile)
  • Edit the scheduled content and check the Devices section
  • Ensure proper device detection is working

Default Content Displayed Instead of Scheduled Content​

No Active Scheduled Content for Slot​

Problem: Default placeholder content shows instead of your scheduled content

Solutions:

  • If nothing is scheduled for the current time and slot, the default content will appear
  • Schedule content for that slot to override the default content
  • Check for gaps in scheduling

Scheduled Content Is Unpublished​

Problem: Scheduled content exists but isn't published

Solutions:

  • Ensure that the scheduled content is published and not in draft mode
  • Only published scheduled content will display on the website
  • Check scheduled content status in the Visual Experience Engine admin panel

Time Zone Confusion​

Scheduled Content Not Displaying at Expected Times​

Problem: Scheduling appears incorrect

Solutions:

  1. Remember that the scheduling uses your local time zone
  2. Adjust the schedule times if your target audience is in a different time zone
  3. Account for daylight saving time changes
  4. Use UTC time for global campaigns when possible

Preview Issues​

Changes Not Reflecting​

Cached Data​

Problem: Scheduled content changes don't appear in preview

Solutions:

  • Clear your browser cache and reload the page
  • Use a hard refresh (Ctrl+F5 or Cmd+Shift+R)
  • Try opening the page in an incognito/private browser window

Unsaved Changes​

Problem: Edits don't appear in preview mode

Solutions:

  • Ensure that you've clicked Save after making changes to the scheduled content
  • Unpublished changes will not appear in the preview
  • Check for any validation errors preventing save

Device Preview Not Accurate​

Incorrect Device Selection​

Problem: Preview doesn't match expected device appearance

Solutions:

  • Verify that you've selected the correct device type in the preview toolbar
  • Switch between Desktop, Tablet, and Mobile views as needed
  • Test on actual devices for accurate representation

Responsive Design Issues​

Problem: Scheduled content doesn't display correctly on certain screen sizes

Solutions:

  • Check the scheduled content design to ensure it's responsive
  • Edit the scheduled content or template to fix any layout issues on specific devices
  • Test CSS media queries and breakpoints

Image and Media Issues​

Images Not Uploading​

File Size Too Large​

Problem: Image upload fails due to size limits

Solutions:

  • Ensure your image files are within the allowable size limits (under 5MB recommended)
  • Compress images if necessary before uploading
  • Use image optimization tools to reduce file size

Unsupported File Format​

Problem: Image format not accepted by the system

Solutions:

  • Use standard image formats: JPG, PNG, GIF, AVIF, WEBP, or SVG
  • Convert any unsupported formats before uploading
  • Check file extensions are correct

Images Not Displaying​

Problem: Images appear as broken or missing

Solutions:

  • Confirm that the images are correctly uploaded and linked in the scheduled content
  • If using external image URLs, ensure they are accessible and correct
  • Check image file permissions on the server

Alt Text Issues​

Problem: Accessibility compliance issues with images

Solutions:

  • While alt text doesn't affect image display, it's required for accessibility
  • Check that the alt text is correctly entered and descriptive
  • Ensure all images have appropriate alternative text

Template Errors​

Template Not Rendering Correctly​

Missing Fields​

Problem: Scheduled content template appears incomplete or broken

Solutions:

  • Ensure all required template fields are filled out
  • Look for any highlighted fields indicating missing information
  • Check template documentation for required vs optional fields

Syntax Errors in Custom Code​

Problem: Custom scheduled content code causes display issues

Solutions:

  • If you've added custom code, check for syntax errors
  • Use the Code View to examine the template code directly
  • Validate HTML, CSS, and JavaScript syntax

Performance Issues​

Slow Loading Times​

Large Media Files​

Problem: Scheduled content loads slowly, affecting user experience

Solutions:

  • Optimize images and videos for web use
  • Use compressed formats and appropriate resolutions
  • Implement progressive loading for large images

Too Much Scheduled Content​

Problem: Page performance degrades with too much scheduled content

Solutions:

  • Limit the amount of active scheduled content on a single page
  • Remove or deactivate scheduled content that is no longer needed
  • Use lazy loading for below-the-fold scheduled content

Script Conflicts​

Other JavaScript Libraries​

Problem: Visual Experience Engine conflicts with existing website JavaScript

Solutions:

  1. Ensure that BILDIT Web Visual Experience Engine scripts do not conflict with other scripts on your website
  2. Check for console errors that might indicate conflicts
  3. Test script loading order and dependencies

Configuration Issues​

Webhook Failures​

Endpoint Not Responding​

Problem: Webhooks not receiving events from Visual Experience Engine

Solutions:

  • Verify endpoint URLs are accessible and properly configured
  • Test webhook endpoints manually with curl or testing tools
  • Check webhook delivery logs in the Visual Experience Engine admin panel

Authentication Issues​

Problem: Webhook requests failing authentication

Solutions:

  • Verify API keys and authentication tokens are correct
  • Check webhook signature validation if implemented
  • Ensure proper headers are configured for webhook requests

Cache Configuration Problems​

Stale Content​

Problem: Content changes not appearing due to caching

Solutions:

  • Check cache invalidation settings
  • Manually clear cache for updated content
  • Verify cache TTL settings are appropriate

Getting Help​

Before Contacting Support​

Have the following information ready:

  • Description of the issue: Clear explanation of the problem
  • Steps to reproduce: How to recreate the problem
  • Error messages: Any error messages received
  • Screenshots: Visual representation of the issue if applicable
  • Environment details: Browser, device, operating system information

Contacting Support​

Email Support​

Email: [email protected]

Include all relevant information about the issue and any troubleshooting steps you've already attempted.

Phone Support​

Phone: 1-800-BILDIT (1-800-245-348)

Phone support is available during business hours for urgent issues.

Self-Help Resources​

  • Documentation: Review this complete documentation set
  • FAQ Section: Check frequently asked questions
  • Community Forums: Connect with other users
  • Video Tutorials: Visual guides for common tasks

Prevention Best Practices​

Regular Maintenance​

  • Monitor system performance regularly
  • Keep software updated to the latest versions
  • Review error logs periodically for potential issues
  • Test critical functionality after any changes

Documentation​

  • Document custom configurations for future reference
  • Keep records of troubleshooting solutions that work
  • Maintain a change log of system modifications
  • Share knowledge with team members

Monitoring​

  • Set up alerts for critical system failures
  • Monitor website performance continuously
  • Track error rates and response times
  • Regular health checks of all integrations

By following this troubleshooting guide and implementing preventive measures, you can maintain a stable and reliable BILDIT Web Visual Experience Engine implementation.