Skip to content

Latest commit

 

History

History
137 lines (97 loc) · 7.25 KB

troubleshooting.md

File metadata and controls

137 lines (97 loc) · 7.25 KB

Troubleshooting

Astro docs: Troubleshooting

Astro's own troubleshooting applies unchanged. What follows are the errors AstroSharp produces.

Diagnostic codes

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.

Build and compilation

"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.

Discovery

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.

Rendering

"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.

Environment and configuration

"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.

At request time

"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.

Things that are not errors

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.