Troubleshooting

Start from the symptom you can observe. Each entry points to the page that owns the current contract and remedy.

The command submit button stays disabled

Required command values must be visible to client validation before submission. Put non-input required values in initialValues, or keep custom controls synchronized through currentValues; a value first created in onBeforeExecute arrives too late to satisfy the validity gate. Follow Building a form for the short rule and CommandDialog advanced features for custom inputs.

Commands or queries do not reach the backend

Components executes commands and runs queries through the generated proxies, which read their runtime configuration from Arc’s <Arc> provider (@cratis/arc.react). CratisComponentsProvider supplies only UI configuration and does not replace it. Check that <Arc> wraps the application, that its origin, basePath, and apiBasePath settings match your host, and that the development server forwards the proxy routes (for example /api and /.cratis) to the backend. Then watch the browser’s network panel for the command or query route. See Getting started and the Arc frontend guide.

Components render without styles

Import @cratis/components/tokens and @cratis/components/styles (or styles/base plus the per-area entries) once at the application entry point, with tokens first. Without them, components render semantic markup with no Cratis structure or appearance. If TypeScript rejects those side-effect imports with TS2882, declare the stylesheet modules as shown in Getting started; do not remove the imports.

A DataPage collapses or its paginator falls off the screen

DataPage fills the height it is given, so an ancestor must have a definite height, such as a sized router outlet, a flex child with min-height: 0, or height: 100vh. Without one it falls back to a small minimum height. See DataPage.

Yarn PnP cannot resolve `rxjs` from Arc React

If you use @cratis/arc.react@22.6.2, that version imports rxjs without declaring it. A strict Yarn PnP consumer needs the version-specific packageExtensions entry and rxjs version shown in Getting started. Arc React 22.16.0 no longer needs this workaround.

Product CSS does not win over Components styles

Import the product stylesheet after the Components tokens and styles entries. Unlayered product CSS wins over the low-priority Components layers; a product that uses its own cascade layers must declare their order explicitly. See the Styling cascade contract and the mixed styling example.

A component import from the package root no longer compiles

The Components 4 package root is setup-only. Import components from explicit subpaths and use the current namespace-to-subpath mapping in Migrate from Components 3 to 4.

An adapter still renders a built-in control

The public adapters implement the declared presentation slots rather than replacing every Components export. With the default rendererFallback='core', undeclared slots use the built-in implementation; rendererFallback='throw' rejects that fallback without adding adapter coverage. See Primitive adaptation: Fallback and Unsupported renderer claims.

Server rendering crashes on a browser global

Use the UI foundation capability matrix to check the server-rendering boundary for the component profile. For a custom portal container, resolve document inside overlayEnvironment.getContainer and return null when it is unavailable, as shown in Choose an overlay container.

Components 3 fails to build after updating PrimeReact to 11.2

@cratis/components 3.x imports @primereact/styles/password, which PrimeReact 11.2.0 renamed to inputpassword. Components 3.6.1 and earlier declare PrimeReact ^11.0.0, so the install succeeds and then a bundler that follows package exports, such as Vite, fails with "styles" is not exported by ... @primereact/styles/password. Later 3.x maintenance releases limit PrimeReact to versions below 11.2.0, so the package manager reports the mismatch instead. Keep primereact and every @primereact/* package at 11.1.x while you stay on Components 3, or move to Components 4, which does not depend on PrimeReact; see Migrating from 3 to 4. The PrimeReact 11 renderer adapter for Components 4 is tested against 11.2.0.