Troubleshooting

Start troubleshooting by identifying which layer is responsible for the problem.

Schema does not render

Check these first:

• The schema object is passed to FluiKit.
• The schema has the expected resource, mode, and view configuration.
• The view you expect to render exists in the schema, such as table, form, detail, or dashboard.
• Field, column, action, and component keys match the names used by the registry.
• Custom renderers are registered before the schema tries to use them.

If a schema key is accepted by TypeScript but does not change the UI, verify that the current VibeFlui runtime consumes that key before documenting or relying on it.

Table data is empty

Check whether the table is using static rows, provider data, or server data.

For static examples, confirm that the data array exists and that each row has stable ids when actions depend on row identity.

For examples using VibeFlui's server/endpoint mode (data fetched from a backend API, called from the browser — VibeFlui itself does not run on a server), confirm that:

• The endpoint returns the shape expected by the provider.
• Query params are mapped by the host app or provider.
• Loading, error, and empty states are handled by the page.
• Row keys used by actions exist in the returned data.

Actions do not run

Check the action flow in this order:

• The action exists in the schema.
• The action key matches the handler key.
• The handler is registered in the registry or passed through the page.
• The handler returns a response object with a status value.
• The action is available in the current view and mode.

Prefer named handler functions in a helper file instead of inline async functions inside the page component.

Custom components do not appear

Check that the component is separated into a component file and registered by key.

Recommended shape:

• components/vibeflui/renderers/... for custom renderers.
• lib/vibeflui/registry.tsx for registry wiring.
• schemas/... for schema objects that reference the registry key.

Do not place JSX directly inside the registry object when the component can live in a reusable component file.

Forms submit but data does not change

Confirm that the form handler updates application state, sends a request to the backend, or invalidates the query used by the table.

For local examples, keep the mutation logic in reusable helper functions. For production examples, keep API calls in application service code and let VibeFlui call the handler.

A documented option does not work

Treat this as a documentation bug until verified.

Check the current VibeFlui source before assuming the option is available. If the source does not include the behavior, report the docs page as needing verification instead of relying on the option.