Errors And Diagnostics

Errors And Diagnostics

Status: Current error classes exist. Diagnostic stability is experimental.

Effuse uses tagged errors for framework failures and structured JSON bodies for server validation and layer-server failures.

Layer Errors

Error	Meaning
LayerBindingNotRegisteredError	A component/hook binding is absent from the active runtime.
LayerNameCollisionError	Two runtime layers use the same global name.
LayerNotFoundError	A requested layer is absent.
DependencyNotFoundError	A declared dependency cannot be resolved.
CircularDependencyError	The dependency graph contains a cycle.
ServiceNotFoundError	A requested service key is unavailable.
LayerSetupError	Setup, lifecycle, or service factory work failed.

Router Errors

The router exposes typed failures for configuration, navigation, guards, and route conflicts. Route parsing validates malformed dynamic segments and ambiguous/colliding normalized paths.

Component Errors

Error	Meaning
PropsValidationError	Initial or updated props failed their runtime schema.
PropsSchemaConflictError	defineProps(schema) and propsSchema supplied different schema sources.
LifecycleError	One or more mount or cleanup callbacks failed after every sibling callback was attempted.

Pass onError to createApp to own lifecycle reporting for that application root. Concurrent roots keep their handlers isolated. Renderer, layer, and SSR teardown preserve multiple causes with AggregateError and continue releasing remaining resources before rejecting.

SSR Errors

SSR error types cover cycles, rendering, validation, hydration, head merging, and plugins. Server validation returns a structured body with source, issues, paths, and messages rather than an untyped thrown string.

Layer Server Errors

LayerServerError carries an error code, status, message, and typed details. Helpers convert it to a stable response body. Client helpers expose status and body information through LayerServerClientError and action errors.

throw new LayerServerError('USER_NOT_FOUND', 'User not found.', {
  status: 404,
  details: { id: params.id },
});

The server serializes this as { error: { code, message, status, details } }. response.error(...) creates the same contract when returning a response is more appropriate than throwing.

Render Errors

Unhandled dynamic render failures produce an element with:

<div role="alert" data-effuse-render-error="true">...</div>

Applications should use explicit error boundaries for product-specific recovery. The default surface exists to prevent silent blank subtrees.

Diagnostic Policy

• Name the failing capability and resource.
• Prefer deterministic errors before user setup runs.
• Preserve structured causes at framework boundaries.
• Do not turn configuration defects into undefined behavior.
• Treat diagnostic text as evolving until a stable compatibility policy exists.

Related

• Layers And Capabilities
• Production Readiness