Troubleshoot Cratis Components

To troubleshoot a Cratis Components screen, start with what you can observe: a disabled button, a missing request, or a table that has not changed. Each points to a different part of the form or data flow. The table below covers those checks, including the library tutorial.

Symptom	Inspect first
Generated import is missing	Backend slice and proxy generation
Components render but are unstyled	CSS entry and bundle
No command/query request leaves the browser	Arc provider and runtime configuration
Request fails or is unauthorized	Request result and backend/authentication logs
Confirm stays disabled	Client validity, visible fields, and hidden required values
Command succeeds but a row is absent	Observable query connection and read-model update
Only layout or product overrides fail	Ancestor height or cascade-layer order

A successful command, a successful query, and a correctly styled screen are separate checks. For example, if no request leaves the browser, inspect the client setup before debugging backend validation. If a request does leave but fails, inspect its result. An empty-state message does not diagnose a failed query, and removing validation or styles to silence a symptom does not repair its cause.

The command submit button stays disabled

Check every required command property, including values the user never types. Client validation must see them 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 enable submission. 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

Use a local CSS entry with @import '@cratis/components/tokens'; followed by @import '@cratis/components/styles'; (or styles/base plus all mounted per-area entries). Import that local file once from the application entry. Add theme only for the Cratis baseline. Without structural CSS, semantic markup can render without the intended structure or appearance.

On TypeScript 6, direct TypeScript imports of package stylesheet subpaths can report TS2882 because they have no type declarations. Prefer the CSS-first setup above with your bundler’s local CSS types, or retain direct imports with the explicit module declarations in Getting started. Do not remove the styles, suppress checking globally, or add a vendor theme to fix this. See Set up styling.

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.

A successful command does not appear in the list

First confirm the command result is successful; a disabled submit button or rejected request is a different branch. The dialog closes on success, but an observable table only changes when its query delivers a result containing the row. Check that the table uses the intended observable query, its arguments match the new data, and its connection is active.

Then inspect the backend read-model update, which supplies the data the query reads. With Cratis Chronicle behind Arc, a projection must process the event into that model before the query can report it. Components neither subscribes directly to Chronicle nor guarantees an immediate read after a successful command. Do not keep registering the same author to force a refresh; each fresh dialog generates another id. See Displaying data.

A detail panel shows the previous author’s books

Compare the selected author with the detail component’s item.id, the authorId passed to BooksForAuthor.use, and the books result you render. They must refer to the same author. The tutorial’s key={String(item.id)} remounts the Books child when the author changes, resetting its React state; it does not guarantee a loading screen or a fresh query result. See List and detail for the argument wiring and status checks. A custom panel must also distinguish failed and unauthorized results from a successful empty book list.

A row action has no selected item

MenuItem.command receives no arguments. Save the typed row from onSelectionChange, read that state in the callback, and pass its id to the dialog. disableOnUnselected controls whether the action is enabled; it does not inject a row. Without a typed details component, supply the explicit DataPage type arguments shown in A list screen with actions.

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.