Skip to content
Nebulas Docs

Troubleshooting

The chat button or form has no styles

Section titled “The chat button or form has no styles”

Tailwind isn’t generating the kit’s classes. Add ./node_modules/@gnomondigital/nebulas-kit-react/dist/**/*.js to content in tailwind.config.ts, and define the CSS tokens (--primary, --background, …). See Installation.

401 Unauthorized with a hint

Section titled “401 Unauthorized with a hint”

Your server couldn’t get a service token. The hint names the strategy it tried. Check the matching block in configureNebulasServer:

Strategy Check
resource_owner_password auth0 + auth0ServiceUser, and that the Password grant is enabled
client_credentials auth0 (Auth0) or entraService (Entra)
service_account serviceAccount: id, key id, private key, and that the public key is registered

In Next.js, also check that every route imports your config module. Each route is loaded separately.

The chat works in one route but not the other

Section titled “The chat works in one route but not the other”

Same cause: /api/a2a/config or /api/nebulas-surfaces/... isn’t importing the module that calls configureNebulasServer.

The form says “This form could not be loaded.”

Section titled “The form says “This form could not be loaded.””
  • nebulasApiUrl isn’t set on the route that serves /api/nebulas-surfaces.
  • The widget name doesn’t match exactly. lead_form never matches lead_form_v2.
  • The widget isn’t published yet, or your credentials can’t see its module.
  • Open the browser’s network tab and look at the render call’s response. The Nebulas error message is passed through.

The form fails with “unknown input”

Section titled “The form fails with “unknown input””

You passed an input (often a utm_* key through trackingParams) that the widget doesn’t declare. Declare it on the widget in Studio (usually hidden: true), or remove it from trackingParams.

A route returns 404 from the surface handler

Section titled “A route returns 404 from the surface handler”

Only render, actions/{name} and theme.css are forwarded. Also check the component’s endpoint prop matches where you mounted the handler.

Changes in Studio don’t show up

Section titled “Changes in Studio don’t show up”

With cache: { enabled: true }, a render can be up to freshMs (3 s by default) old. After that, it’s checked against the widget’s last update. Reload after a few seconds.

Conversations don’t appear in Nebulas

Section titled “Conversations don’t appear in Nebulas”
  • Pass nebulasBaseUrl to the chat and mount the Nebulas proxy. See Full-page chat.
  • Check that /api/a2a/config returns a non-null nebulasProjectId.

Charts render as nothing

Section titled “Charts render as nothing”

Install the optional vega-embed peer dependency.

Debugging

Section titled “Debugging”

configureNebulasServer({ debug: true }) logs every Nebulas API response body on the server. Turn it off afterwards, because response bodies can contain user data.