Troubleshooting

Troubleshooting

A URL renders the not-found page

Check RootPageNamespace, PageAssembly, the page namespace, class name, and BasePage inheritance. / requires a Default class. Normal type lookup is case-insensitive, but the class must be in the configured assembly.

If the URL is data-driven, configure OnNotFound and return the page type. Return null for paths it does not own.

Query properties do not bind

Property names are case-sensitive. The property must be public and writable, and its type/value must be supported. Enum values are case-sensitive and must name a defined enum member. Invalid values are ignored rather than reported; validate required input explicitly.

StaticResourceNotFoundException

The page or reusable layout resource name is wrong or the file is not embedded. Confirm the .csproj EmbeddedResource item and inspect:

typeof(Program).Assembly.GetManifestResourceNames()

[PageTemplate] needs the full manifest name. Template.Site looks beneath RootTemplateNamespace for Site.htm.

Template XML fails to parse

Templates must be well-formed XML, not permissive HTML. Close elements, quote attributes, escape ampersands, and keep exactly one root (PageTemplate or Template).

Dynamic method cannot be found or bound

The method must be public, on the page type, and named exactly after Dynamic.Name. Its signature is Task Name(TextWriter, DynamicContentArgs). Loop sources are public parameterless methods returning IEnumerable.

Template changes do not appear

Resources are embedded at build time and compiled/cached at runtime. Rebuild and restart the process. Hot reload of the source .htm file does not replace an already embedded resource.

Static files return the Imp 404 page

Register UseStaticFiles() before UseImp(). Confirm the asset is under the configured web root and its URL is correct.

Secure page is still public

[SecurePage] requires an Authenticate callback. Also ensure UseAuthentication() runs before Imp and the callback returns false for unauthenticated users.

POST succeeds without antiforgery validation

Imp does not validate tokens automatically. Register AddAntiforgery, render a token, and call ValidateRequestAsync inside every state-changing postback.

Synchronous I/O exception under Kestrel

Use Imp 0.1.1 or later. The response writer was changed to remain asynchronous for modern Kestrel. Do not enable AllowSynchronousIO as a workaround unless unrelated legacy code requires it and the risk is understood.

Middleware after Imp never runs

Imp is terminal and does not invoke the next delegate. Move required middleware before Imp or use an explicit branched pipeline.

Report an issue

Include Imp/package and .NET versions, OS, minimal page/template, path/query, full exception/stack trace with secrets removed, and whether the issue reproduces in the Todo sample. File reports at KitchenPC/Imp issues.