Maintenance & Troubleshooting

The maintenance tools live at the bottom of Settings → Voxel Ads.

Tools

Bulk re-sync

Walks every banner post and rebuilds its AdRotate advert. Run it after:

• Changing field keys or the CPT key
• Changing the plan → group mapping
• Installing Voxel Ads on a site that already has banner posts

It processes in batches of 200 with cache flushes between batches, so it's safe on large catalogues.

Orphan finder

Lists links broken in either direction:

• Posts with stale AdRotate IDs — the banner points at an advert that no longer exists.
• AdRotate adverts with no post — an advert whose banner post was deleted.

Each gets a one-click cleanup. Worth running after a bulk import or a database restore.

Flush stats cache

Clears cached statistics and schedule reads. Only needed if you've edited AdRotate's tables directly — normal activity invalidates the cache by itself, immediately, as impressions and clicks are recorded.

Geo tools

Test IP lookup resolves any IP with your configured provider, so you can verify targeting without a VPN. Flush geo cache clears all cached visitor lookups.

Troubleshooting

There's no settings menu

The settings screen only registers once both the Voxel theme and AdRotate are active. Check the admin notice at the top of any dashboard page — it names what's missing and offers to install AdRotate for you. See Installation.

Banners don't reach AdRotate

Check the CPT key and field keys in settings against the Voxel post type. Then run Bulk re-sync and watch whether the advert appears.

Banners reach AdRotate but never show on the front end

Almost always the group mapping. A banner in no group is invisible to every [adrotate group="N"] placement. Check the plan key spelling and set a Fallback group ID.

Ads don't appear in feeds

In order:

1. Is feed injection enabled?
2. Does the rule's target selector match the feed's actual container?
3. Is the rule enabled=no?
4. Does a geo=, terms=, days= or hours= restriction exclude you right now?
5. Has the per-rule max or the global cap already been reached?

Remember that targeting is server-side: if you don't match, the markup was never sent, so there's nothing to find in the page source.

Stats show zeros

Statistics only appear once AdRotate records the first impression or click. Check AdRotate → Settings → General → Tracker is enabled.

Preview cards show the wrong numbers

Voxel caches preview-card HTML. Use dynamic tags in cards rather than the stats widget — they re-evaluate per listing. See Statistics & Widgets.

A feed shows raw [adrotate ...] text

The AdRotate shortcode isn't registered, which means AdRotate is deactivated. Reactivate it. Voxel Ads suppresses unrendered shortcodes rather than printing them, so if you're seeing this, check whether an older version is installed.

Expired banners leave blank slots

They shouldn't. Expired banners are excluded from explode selection, AdRotate's "not available" response is stripped before rendering, and a daily task demotes expired adverts to disabled. If you see one, run Bulk re-sync or wait for the next daily pass.

Dayparted ads show at the wrong time

Full-page caching. A page cached at 10:00 keeps serving its 10:00 ads until the cache expires. Shorten the TTL or exclude dayparted pages.

Updates aren't appearing

Check Settings → Voxel Ads → License shows an active license. An expired or deactivated license withholds updates — ad serving continues regardless.

Scheduled task

Voxel Ads registers one daily task that demotes schedule-expired adverts from active to disabled, keeping AdRotate's admin lists accurate, and sends expiry warnings. Only adverts Voxel Ads manages are touched — anything you created directly in AdRotate is left alone. Renewals reactivate automatically on the next sync.

Deactivating the plugin removes the scheduled task.