Troubleshooting
Common issues and solutions for the Onpane widget. All widget log messages are prefixed with [Onpane] in the browser console.
Widget Not Appearing
If the announcement bar does not show up on your site:
- Open the browser console and look for messages starting with
[Onpane] - Verify your API key is correct (should start with
onpane_live_) - Ensure you have an active (non-draft) announcement
- Check that the announcement's start date has passed
- Check that the end date (if set) has not passed
- Confirm the script tag uses the
data-keyattribute with your API key
Console Messages
The widget logs specific messages to help with debugging. These appear in your browser's developer console:
| Message | Level | Cause |
|---|---|---|
[Onpane] Missing data-key attribute | warn | The script tag is missing the data-key attribute. Add it with your project API key |
[Onpane] Invalid API key format | warn | API key does not start with onpane_live_ (or onpane_test_ for testing). Check for typos |
[Onpane] No announcement data to display | warn | API returned successfully but no announcement is active. Create and activate an announcement in the dashboard |
[Onpane] No active announcement found | warn | API returned 404 -- no active announcement for this project |
[Onpane] Failed to fetch announcement: {<status>} | warn | Network error or server error. Check your internet connection and that the API key is valid |
[Onpane] Announcement dismissed for this session | log | The visitor has already dismissed this announcement in the current browser session |
[Onpane] Announcement dismissed by user | log | The visitor has a persisted dismissal for this announcement that has not yet expired |
[Onpane] Placeholder #{<id>} is hidden (display:none)... | warn | A placeholder element exists but has display: none. The widget falls back to default positioning |
Z-index Conflicts
If the announcement bar appears behind other elements like modals, headers, or sticky navigation, increase its z-index:
onpane-announcement {
--onpane-z-index-override: 999999;
}The default z-index is 9999. Set --onpane-z-index-override on the onpane-announcement element to a higher value.
CSP (Content Security Policy) Errors
Symptom: Console shows "Refused to load the script" or similar CSP violation errors.
Solution: Add https://onpane.com to your script-src directive:
Content-Security-Policy: script-src 'self' https://onpane.com;If you're using a <meta> tag for CSP, add https://onpane.com to the script-src list. If your policy also restricts connect-src, add https://onpane.com there as well for API calls.
Ad Blocker Interference
Symptom: Widget loads inconsistently or not at all for some users.
Possible causes:
- Some ad blockers block third-party scripts that appear to be marketing-related
- Browser extensions may interfere with widget loading
Solutions:
- Test in an incognito/private window with all extensions disabled to confirm this is the cause
- If confirmed, you may ask users to whitelist your domain in their ad blocker
- Note that some aggressive ad blockers will block regardless of whitelisting
The Onpane widget is designed to be lightweight and non-intrusive. Most ad blockers do not interfere with it, but some particularly aggressive blockers may.