Astro's own troubleshooting applies unchanged. What follows are the errors AstroSharp produces.
Everything AstroSharp reports carries a code, printed before the message:
ASHP0102 No compiled component type found for index.razor (src/pages/index.razor)
A code identifies the diagnostic; the wording is free to improve without it becoming a different
thing. Roslyn's own diagnostics keep their own ids (CS0103, RZ10011) and pass straight through.
| Code | What it means |
|---|---|
ASHP0001 |
dotnet build of the generated project failed. The compiler's own errors follow it. |
ASHP0002 |
The build reported success but produced no assembly. |
ASHP0003 |
The compiled assembly could not be loaded. |
ASHP0004 |
A recompiled assembly could not be swapped in. Dev keeps serving the last good one. |
ASHP0005 |
The project declares more than one startup class. |
ASHP0006 |
A startup class could not be constructed, has the wrong shape, or threw. |
ASHP0007 |
Discovery refused a type. The message names it and what to change — see below. |
ASHP0008 |
A component render threw, or the renderer named a component that does not exist. |
ASHP0100 |
Hot reload is running a full dotnet build per save; the in-process compiler is gone. |
ASHP0101 |
An in-process compile failed unexpectedly and fell back to dotnet build. |
ASHP0102 |
A .razor file on disk has no matching compiled component type. |
ASHP0103 |
GetLayoutProps has a signature that cannot be called, so it was ignored. |
ASHP0104 |
GetLayoutProps threw, so the layout got only the route's props. |
ASHP0105 |
A <style> block interpolates, so the build could not lift it through Vite. |
ASHP0106 |
A <script> block interpolates, so the build could not lift it. |
ASHP0001–ASHP0008 are errors and stop the build; ASHP0100 upward are warnings.
"the C# project failed to compile" — a Roslyn error. The diagnostics above it carry the file and
line and read the same as dotnet build output. At startup this stops the build.
"the C# project does not compile, so this page cannot be rendered from the current source" — the same thing in dev, after a failed hot reload. The dev server stays up but stops serving what last compiled: an open page gets Vite's error overlay, and a fresh request gets a 500. Fix the error and save; the next successful compile clears it. See Develop and build.
"No compiled component type found for X.razor" — the .razor file did not produce a component
type. Usually a Razor syntax error, or a file whose name cannot be turned into a class name.
"Astro's addPageExtension hook is unavailable on this Astro version" — the hook .razor page
routing depends on is missing. Check your Astro version; see Upgrade.
These fail the build rather than silently skipping the type, because the symptom otherwise shows up much later as a missing action or an empty collection.
"this class carries [AstroAction] but was not exposed as an action" — the attribute selects
nothing on its own. Implement IAstroAction<TInput, TOutput>. See Actions.
"declares X as a ContentReference but does not say which collection it points at" — add
[References("collection-name")]. The type cannot carry it, since a collection is named by a
string. See Content collections.
"declares X as a ContentReference. References are a content-collection feature" — an action input
cannot hold one: there is no store behind it to resolve against. Take the id as a string.
"takes AstroContext in its constructor, but AstroContext is the per-render Astro global" — a loader, endpoint, action or middleware does not run during a render. Take the individual services instead; see Services and startup.
"A collection can only have one loader" — two classes claim the same Collection name.
"client:load was used on X" — a C# component can only be an island with
client:only="astrosharp", under client rendering. Use that, or move the
interactive part to a framework component.
"no browser host was built" — client:only without experimental: { clientRendering: true }.
"X reads Astro, so it cannot be an interactive island" — the context is rebuilt per render from
what the server forwards. Pass what the component reads as a prop.
"AstroSharp: Render of X failed: ..." — a C# component threw. The build fails with the exception's message rather than quietly leaving a hole in the page, and anything the component logged on its way down is emitted first.
In dev the same failure is a 200 with a truncated body, because Astro streams HTML and has already committed the status by the time C# throws — the error goes to the terminal and the dev overlay.
"a deferred call left an unresolved placeholder in the output" — a DeferredValue was rendered
somewhere the substitution could not reach, most likely serialized into a prop. Use CallAsync. See
Runtime API modules.
"The environment variable X is declared in env.schema as required, but is not set" — exactly what
it says. Set it, give it a default, or mark it optional. See
Environment variables.
"experimental.serverRendering must be 'off', 'sidecar', or 'wasm'" — an unknown value, reported at setup rather than ignored.
"The AstroSharp host is not running" — something reached the host outside a build, most often a live collection or an action on a route with no on-demand rendering configured. See On-demand rendering.
"needs a channel back to Astro" — Astro.Content, Astro.Assets or Module.CallAsync was used
under serverRendering: 'wasm', which has no route back to Node. All three work during the build, in
dev, and under 'sidecar'.
"reading a content collection from C# needs astro:content" — the module could not be loaded in this environment. Usually the same cause as above.
"cannot use server-rendered pages without an adapter" — Astro's own message. A page declared
[AstroPage(Prerender = false)], which needs an adapter as any on-demand route does.
"Remote image ... is not allowed by your image configuration" — Astro's own rule. Add the host to
image.domains or image.remotePatterns. See Images.
A dev server restart on a routing change is expected — endpoints, the first middleware and a
page's prerender are registered at startup. See
Develop and build.
An unconfigured Astro.I18n answering rather than throwing is deliberate: with no i18n block,
every helper returns the path unchanged so a component still renders. Check IsConfigured when you
need to care.
Session and cache writes being discarded on a prerendered route is deliberate too, and matches
Astro. Check IsAvailable / Enabled.