Troubleshooting

Build errors

could not find a source for ./dist/client/X.js

The export points to an output path with no matching source. svebcomponents maps dist/client to src and looks for one of src/X.svelte, src/X.ts, or src/X.js.

Match the export basename and letter case to the source file. Use manual configuration if your source and output paths follow another pattern.

multiple sources match ./dist/client/X.js

The source directory contains more than one candidate, such as src/X.svelte and src/X.ts. Rename one file or declare the entrypoints in manual configuration.

could not find expected ESM ssr export

An export key ending in /ssr needs a default or import condition:

{
  "./ssr": {
    "types": "./dist/server/ssr.d.ts",
    "default": "./dist/server/ssr.js"
  }
}

no valid configuration found

svebcomponents found neither svebcomponents.config.ts nor an export that points into ./dist/client/. Add the exports from Configure package outputs or create a config file.

custom-elements.json is not exposed to consumers

svebcomponents wrote the manifest, but your package does not publish a path to it. Add both fields:

{
  "customElements": "custom-elements.json",
  "files": ["dist", "custom-elements.json"]
}

Build warnings

Unsupported customElement tag syntax

auto-options reports either warning when it cannot find a literal tag:

• A dynamically-interpolated customElement string tag is not supported
• The bare customElement boolean shorthand is not supported

auto-options needs a string literal for the tag. If it cannot read one, it leaves <svelte:options> unchanged and skips the prop metadata and hydration wrapper. Use either supported form:

<svelte:options customElement="my-element" />
<!-- or -->
<svelte:options customElement={{ tag: "my-element" }} />

cannot infer a single attribute type for a union mixing […]

A union such as string | number has no single attribute converter, so auto-options uses String. Narrow the type or set the converter:

<svelte:options
  customElement={{ props: { value: { type: "Number" } } }}
/>

Unions with one primitive kind, such as string | null or "a" | "b", map to that kind.

could not resolve prop types since they were not of expected shape

auto-options can inspect an object type, an interface, or a local type alias on $props(). Move imported prop types into the component or write the metadata by hand.

skipping file in the custom elements manifest: it could not be parsed

The analyzer could not parse the component. The build omits that element from the manifest and generated types. Check the preceding parser error.

Server errors

await_invalid

Svelte throws this error when a component awaits during a synchronous server render. Follow the setup for async components.

AsyncRendererError: <my-element> renders asynchronously…

Your host called a synchronous path for a component that awaits during render or in its <entry>.ssr.ts preparation hook. Use an await-capable host path. React’s standard wrapper emits the host element without shadow content in this case; its React Server Component path can await.

Custom element my-element not found

Your server has not imported the browser entrypoint, so its custom-element registry has no constructor for the tag. Import the component package before the host renders the element.

Custom element renderer for my-element not found

The custom element exists, but the renderer registry has no matching entry. Import the package’s /ssr export once from server setup:

import "my-component-package/ssr";

A generated renderer registers itself when svebcomponents can read the tag at build time. Register dynamic tags in code:

import { ElementRendererRegistry } from "@svebcomponents/ssr";
import MyComponentRenderer from "my-component-package/ssr";

ElementRendererRegistry.set("my-component", MyComponentRenderer);

Could not access custom element constructor for tag: my-element

Your code registered a renderer before it defined the custom element. Import the browser entrypoint before you call ElementRendererRegistry.set().

Browser messages

<my-element> declares slots and was mounted instead of hydrated

svebcomponents mounts components that declare <slot> instead of hydrating their server nodes. The rendered result remains usable, but the upgrade replaces the shadow content. See Hydration.

Svelte logs hydration_mismatch and re-renders

The server and browser produced different structures. Check conditional branches, list lengths, and elements that depend on browser-only state. Pass the same props into both renders. The async components guide covers server preparation hooks.

During hydration_mismatch recovery, Svelte clears the affected content and mounts the component. Some text, attribute, and {@html} differences use other warnings and recovery paths.

Ask for help

Open an issue in svebcomponents/svebcomponents with the error and a minimal reproduction.