> ## Documentation Index
> Fetch the complete documentation index at: https://trueforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common failure modes and their causes.

<AccordionGroup>
  <Accordion title="Error: requires an AuiProvider">
    Deduplicate the assistant-ui singletons `react`, `react-dom`, `@assistant-ui/core`, `@assistant-ui/react`, and `@assistant-ui/store` must each resolve to exactly one copy in your bundle. Two copies produce a runtime error along the lines of *"requires an AuiProvider"*.

    <CodeGroup>
      ```ts vite.config.ts theme={null}
      export default defineConfig({
        resolve: {
          dedupe: [
            "react",
            "react-dom",
            "@assistant-ui/core",
            "@assistant-ui/react",
            "@assistant-ui/store",
          ],
        },
      });
      ```

      ```json package.json theme={null}
      {
        "resolutions": {
          "@assistant-ui/core": "<version>",
          "@assistant-ui/store": "<version>"
        }
      }
      ```
    </CodeGroup>

    The `vite.config.ts` approach is usually enough. Reach for `resolutions` (or `overrides` on npm, `pnpm.overrides` on pnpm) when a transitive dependency drags in a second copy.

    Note that `@assistant-ui/store` arrives transitively through `@assistant-ui/core` rather than being declared by the SDK, so there is no published version to look up — pin it to whatever your lockfile resolves `@assistant-ui/core` against.
  </Accordion>

  <Accordion title="The UI renders but is collapsed to zero height">
    The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.

    ```tsx theme={null}
    <div className="flex h-dvh min-h-0 w-full flex-1 flex-col">
      <TrueForgeUI /* ... */ className="h-full min-h-0" />
    </div>
    ```

    The SDK fills its parent container and does not set its own height. A parent with no resolved height collapses the entire chat UI, which is the single most common cause of a "blank" first install.
  </Accordion>

  <Accordion title="The SDK renders unstyled">
    Check that `@import "@truefoundry/trueforge-ui/styles.css";` is actually reaching the browser — that single import is the entire styling setup, and the stylesheet is self-contained. You do not need Tailwind in your own app for the SDK to look right.
  </Accordion>

  <Accordion title="Your app's own base styles changed after installing">
    The SDK's stylesheet deliberately omits Tailwind preflight so it cannot reset your styles, so this is unlikely to come from the import itself. Look instead at whether you added `@import "tailwindcss";` at the same time — that one does ship preflight, and it resets host styles by design.
  </Accordion>

  <Accordion title="An error alert appears immediately on mount">
    The built-in server failed to resolve. For `type: "trueforge"`, confirm `@truefoundry/trueforge-sdk`
    is installed, `baseUrl` is reachable, and you passed either `token` or a working `fetch` — see
    [Quickstart](/ui-sdk/get-started/quickstart). Attach an `onError` handler to see the underlying error.
  </Accordion>

  <Accordion title="Requests fail in composer mode with an unknown model">
    Without an explicit `defaultAgentSpec`, drafts default to `openai-main/gpt-4.1`. Pass a spec naming a model your backend actually exposes: `agentConfig={{ mode: "AgentComposer", defaultAgentSpec: { model: { name: "..." } } }}`.
  </Accordion>

  <Accordion title="Changing defaultAgentSpec did not affect the open conversation">
    It seeds a new draft rather than binding to the current one, so the change lands on the next **new chat**. Clear chat will not pick it up — that path preserves the spec already bound to the draft. To apply it to the conversation on screen, remount the component with a new `key`. It is ignored entirely in `SingleAgent` mode.
  </Accordion>

  <Accordion title="The settings button is missing">
    Settings render only when your server exposes a `catalog`, so attach one to enable the panel. If you are on a custom layout, that is the other cause — the panel ships with the built-in layouts only.
  </Accordion>

  <Accordion title="Only the OAuth screen renders — no chat">
    A `screenType=mcp-auth` query parameter is present on the URL. `TrueForgeUI` renders the OAuth completion screen exclusively in that case. Keep the callback on its own route; see [MCP OAuth](/ui-sdk/setup-custom-ui/mcp-oauth).
  </Accordion>

  <Accordion title="Dark mode fights with the host application">
    The provider toggles the `dark` class on `document.documentElement`. Pass a controlled `theme.mode` derived from your own state so the two stay aligned.
  </Accordion>

  <Accordion title="Import of AskUserPrompt fails">
    A few names are published as types only, so importing them as values fails.
    `AskUserPrompt`, `McpAuthPrompt`, and `ReasoningCard` are override-only — supply your own
    component typed with the published props. `Button` / `IconButton` are public values restyled
    through [theme tokens](/ui-sdk/setup-custom-ui/custom-theme), not slot overrides.
  </Accordion>

  <Accordion title="SSR or React Server Components errors">
    The package is ESM-only and client-only. Mount `TrueForgeUI` from a client component — in Next.js App Router, a file with `"use client"` at the top.
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.