# Troubleshoot JSX

Start by checking that the file uses the automatic Pibbl runtime. Project-wide
TypeScript should set `"jsx": "react-jsx"` and
`"jsxImportSource": "@pibbl/core"`; a mixed project can put
`/** @jsxImportSource @pibbl/core */` before imports in a Pibbl file.

Development JSX records source filename, line, and column through `jsxDEV`.
When available, Pibbl appends that location to child, component, and style
diagnostics. Production descriptors omit it.

## Compile-time diagnostics

| Symptom                                                                  | Meaning and correction                                                                                          |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| Cannot find `@pibbl/core/jsx-runtime` or `jsx-dev-runtime`               | Install a current `@pibbl/core`, use package exports, and do not alias a private source path.                   |
| Lowercase tag is missing from `JSX.IntrinsicElements`                    | Pibbl has no intrinsic HTML tags. Import and use a descriptive uppercase component.                             |
| A Promise-returning or `async` component is not a valid JSX element type | Pibbl components are synchronous. Resolve data outside the render and schedule an ordinary update.              |
| A React element is not assignable to `PibblNode`                         | The file or value belongs to another renderer. Split the files or use the minority tree's explicit constructor. |
| Property `children` does not exist                                       | The drawing leaf rejects children. Put siblings in `Group`, another container, or a fragment.                   |
| A Pibbl element is not assignable to `PibblTextChild`                    | `Text` accepts scalar textual content, not components. Move the element outside `Text`.                         |
| Required `style` or a required style member is missing                   | Supply the component's closed local style.                                                                      |
| `key` or `style` makes custom program props invalid                      | Those names are reserved construction/primitive metadata; rename the application prop.                          |
| Percentage-capable primitive style requires `resolveStyle`               | `definePrimitive` must resolve allocation syntax to a finite resolved type.                                     |

Pibbl does not install a global JSX namespace. Editor types must resolve the
module-scoped namespace from the compiler entry. If an editor shows React
intrinsics in a Pibbl-only file, inspect that file's compiler configuration and
restart its TypeScript project after correcting it.

## Exact runtime diagnostics

### React runtime selected

```text
Pibbl received a React element. This file is using the React JSX runtime.
Set jsxImportSource to "@pibbl/core" or add /** @jsxImportSource @pibbl/core */.
Received by <receiver>.
```

This can occur at the root or in nested content. Correct the file's JSX runtime
or move the React and Pibbl JSX to separate files.

### Other foreign element descriptor

```text
<receiver> received an element-like object that was not created by @pibbl/core as a Pibbl child.
Check this file's JSX runtime and set jsxImportSource to "@pibbl/core".
```

Do not forge or spread a descriptor. Use JSX or `createElement`, both of which
install Pibbl's stable `Symbol.for("@pibbl/core.element")` runtime brand.

### Direct platform-component call

```text
Rectangle is a Pibbl component and was invoked outside the Pibbl renderer.
Use <Rectangle ... /> in a Pibbl JSX file or createElement(Rectangle, props).
```

The name changes to the invoked component. A platform component value describes
work only when used as an element type; it is not a callable factory.

### Invalid child

```text
<receiver> received <description> as a Pibbl child.
```

Descriptions are exact: `a non-empty string`, `a nonzero number`, `a function`,
`a symbol`, `a Promise`, `an async iterable`, `an unsupported <typeof> value`,
`an unsupported object`, `a Pibbl element inside textual content`, or
`duplicate Pibbl key "<key>"`. Put raw text/numbers inside `Text`, await outside
rendering, use finite synchronous lists, and give flattened siblings unique
keys.

### Policy child count and configuration

```text
FocusManagement requires exactly one Pibbl element child after empty values are removed; received <count>.
KeyboardNavigation requires exactly one Pibbl element child after empty values are removed; received <count>.
KeyboardNavigation mode must be "directional".
KeyboardNavigation requires an active FocusManagement focus manager.
```

Keep one component element beneath each transparent policy and nest
`KeyboardNavigation` inside `FocusManagement`. Duplicate applications also
report that the same policy cannot be applied more than once to one element.

### Render-context access

```text
Pibbl hooks can only be called while rendering a component.
useCanvasContext() is available only during Pibbl rendering and cannot be used during pure measurement.
No Pibbl layout context is available
```

Create elements instead of directly invoking components. Keep hooks and render
accessors in synchronous component rendering, and keep primitive measurement
pure.

### Layout diagnostics

`LayoutDiagnostic` has this stable shape:

```text
<component>: property <property> received <value> during <algorithm>; constraints <constraints>; <reason>
```

The error object also exposes `component`, `property`, `suppliedValue`,
`algorithm`, and `constraints`. Correct the named non-finite, unsupported,
unresolved, or out-of-range value rather than coercing it after resolution.

Focused source and built coverage lives in
[`foreign-runtime-diagnostics.test.tsx`](https://github.com/benlesh/pibbl/blob/main/packages/core/src/lib/element/foreign-runtime-diagnostics.test.tsx).

## Implementation guidance for agents

Read the [Authoring, signals, and lifecycle companion](/agents/topics/lifecycle/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.