Skip to main content

Troubleshooting

This page covers the most common issues you might encounter when using the Widget Builder and how to resolve them.

Widget doesn't appear in Staffbase​

Your widget is built and saved, but it doesn't show up when you try to add it in Staffbase.

Cause: The widget is not marked as available, or the Widget Bundle URL needs to be registered.

Solution:

  1. Open your widget in the Widget Builder and go to the General tab.
  2. Make sure the Available in Staffbase toggle is enabled.
  3. Click Save.
  4. If the widget still doesn't appear, go to Settings > Widget Bundle URL and click Re-register to refresh the registration with Staffbase.

API request returns CORS errors​

Your widget's API call fails in the browser console with a message like Access-Control-Allow-Origin or CORS policy.

Cause: The external API you are calling does not allow direct requests from a browser.

Solution: Enable the Route through Widget Builder option in the API tab of your widget. This proxies the request through the Widget Builder server, avoiding CORS restrictions entirely.

See the API Proxy guide for details on how the proxy works and how to configure authentication headers.

Widget preview shows an error​

The live preview panel in the editor displays an error instead of your widget.

Cause: This is usually caused by an unreachable API endpoint, an invalid API response, or a Handlebars syntax error in your template.

Solution:

  1. Go to the API tab and check the response status and body. Since v3.3, the preview shows the HTTP status code and full response body for easier debugging.
  2. Verify the API endpoint URL is correct and reachable.
  3. Switch to the Layout tab and look for Handlebars compilation error markers in the editor — these highlight syntax issues like unclosed tags.
  4. Fix any errors and the preview will update automatically.

Changes not reflected in Staffbase​

You updated your widget in the Widget Builder, but the Staffbase page still shows the old version.

Cause: The changes haven't been saved, or the browser is serving a cached version.

Solution:

  1. Make sure you clicked Save in the Widget Builder after making changes.
  2. Refresh the Staffbase page — there is no need to remove and re-add the widget.
  3. If the old version persists, try a hard refresh with Ctrl+Shift+R (Windows/Linux) or Cmd+Shift+R (Mac) to bypass the browser cache.

"Powered by JASP" text at bottom of widget​

A small "Powered by JASP" line appears below your widget when it renders in Staffbase.

Cause: This branding text is displayed for widgets on the free plan.

Solution: Upgrade to a paid plan to remove the branding. You can manage your subscription in Settings > Billing.

Cannot access the Widget Builder​

You see a permission error or blank page when trying to open the Widget Builder.

Cause: Your Staffbase account may not have the required permissions, or the OAuth integration is misconfigured.

Solution:

  1. Confirm that your Staffbase account has an Administrator role.
  2. Check that your Staffbase group has been granted access under Settings > Permissions in the Widget Builder.
  3. Verify the OAuth client is properly configured — see the Initial Setup guide for the full configuration steps.

Widget Bundle URL registration failed​

You copied the Widget Bundle URL from the Widget Builder but it didn't work when you tried to register it in Staffbase.

Cause: The URL may not have been pasted correctly, or the Staffbase Custom Widgets settings page requires a specific format.

Solution:

  1. In the Widget Builder, go to Settings and copy the Widget Bundle URL.
  2. In Staffbase Studio, navigate to Custom Widgets settings.
  3. Paste the URL exactly as copied and click Install.
  4. If it still fails, double-check that your Widget Builder instance is reachable from Staffbase. See the Initial Setup guide for the full walkthrough.

Handlebars template errors​

The layout editor shows warnings or your widget renders incorrectly due to template issues.

Cause: Handlebars templates require strict syntax — missing closing tags and incorrect brace usage are the most common mistakes.

Solution:

  • Make sure every block helper has a matching closing tag: {{#if}} needs {{/if}}, {{#each}} needs {{/each}}.
  • Use double braces {{ }} for escaped output (recommended for most cases).
  • Use triple braces {{{ }}} only when you need to render unescaped HTML.
  • Check the Handlebars reference for the full list of supported helpers and syntax.

API data not loading in preview​

The preview panel is empty or shows "No data" even though you have configured an API endpoint.

Cause: The data may not have been fetched yet, or the API configuration has an issue.

Solution:

  1. Open the API tab and click Load Data to fetch a fresh response.
  2. Verify the API endpoint URL is correct and accessible.
  3. If the endpoint requires authentication, make sure the tokens or headers are configured in the API settings.
  4. Check the JSON response format in the preview panel — your Handlebars template needs to reference the correct field names from the response.

Widget looks different on mobile​

Your widget looks great on desktop but the layout breaks or looks wrong on smaller screens.

Cause: The template may not include responsive styles for different screen sizes.

Solution:

  1. Use the device preview buttons (mobile, tablet, desktop) in the layout editor to test how your widget renders at different widths.
  2. Apply Tailwind CSS responsive prefixes in your template: sm: for small screens, md: for medium, and lg: for large.
  3. See the Tailwind CSS guide for responsive design patterns and examples.

Still need help?​

  • Check the FAQ for answers to frequently asked questions.
  • Contact our support team at support@jasp.eu if your issue isn't covered here.