Blazor: 'Found markup element with unexpected name' (RZ10012)

warning RZ10012: Found markup element with unexpected name 'CustomerCard' means the Razor compiler could not find a component called CustomerCard in any namespace the page can see, so it treated the tag as plain HTML. Add a @using line for the component's namespace to _Imports.razor and the warning goes away.

The namespace of a Razor component follows its folder. A component in Components/Customers lives in YourApp.Components.Customers, and the template's _Imports.razor does not know about that folder until you add it.

The error

...\FixLab\Components\Pages\Home.razor(7,1): warning RZ10012: Found markup element with unexpected name 'CustomerCard'. If this is intended to be a component, add a @using directive for its namespace. [...\FixLab\FixLab.csproj]
    1 Warning(s)
    0 Error(s)

The paths were shortened; nothing else in the output changed. Note the last two lines: the build succeeds, which is why this one is easy to miss in a long build log.

Why it happens

Every .razor file compiles to a C# class, and unless the file says otherwise with @namespace, its namespace is the project's root namespace plus the folder path. Components/Pages/Home.razor becomes FixLab.Components.Pages.Home, and Components/Customers/CustomerCard.razor becomes FixLab.Components.Customers.CustomerCard. When the compiler meets a tag that starts with a capital letter, it looks for a component of that name in the page's own namespace and in every namespace brought in with @using, either in the page or in an _Imports.razor above it.

The Blazor Web App template's _Imports.razor imports FixLab.Components and FixLab.Components.Layout, not the folders you add later. A sibling namespace like FixLab.Components.Customers is not visible from FixLab.Components.Pages, so the compiler keeps <CustomerCard> as an ordinary markup element and warns instead of failing. That is the usual way to meet RZ10012: you move a component into a new folder, or create one there, and use it from a page in another folder. The page then sends the tag to the browser as it is, and the component's own markup never appears:

<CustomerCard Name="Maria Garcia" Email="maria.garcia@example.test"></CustomerCard>

The fix

Add the namespace to Components/_Imports.razor (the last line is the new one):

@using FixLab
@using FixLab.Components
@using FixLab.Components.Layout
@using FixLab.Components.Customers

The next build is clean:

Build succeeded.
    0 Warning(s)
    0 Error(s)

One line in _Imports.razor covers every page in and below that folder, which is what you want for a component used in several places. If you would rather not import the namespace, the fully qualified tag also builds without the warning:

<FixLab.Components.Customers.CustomerCard Name="Maria Garcia" Email="maria.garcia@example.test" />

It works, but it is long, so keep it for a one-off use or for two components that share a name.

How it was reproduced

A fresh Blazor Web App from dotnet new blazor -n FixLab -int Server on .NET SDK 10.0.401 (net10.0). A two-parameter component was added at Components/Customers/CustomerCard.razor and used in Components/Pages/Home.razor without any @using. dotnet build printed the warning above. Adding the @using line gave a build with 0 warnings, and so did the fully qualified tag with the import removed again.

Frequently asked

How do I fix RZ10012 found markup element with unexpected name?

Find the namespace of the component, which is the project namespace plus its folder path unless the file sets @namespace, and add a @using line for it to _Imports.razor or to the page. Rebuild and the warning disappears.

Why does my Blazor component render as an HTML tag instead of the component?

The compiler could not find a component with that name in the namespaces the page imports, so it kept the tag as plain markup and raised warning RZ10012. The build still succeeds, so check the build output for that warning.

Do I need a @using for every folder of components in Blazor?

For each folder whose components you use from a page in a different folder, yes. One line in _Imports.razor covers every Razor file in that folder and its subfolders, so most projects add one line per component folder there.

More decoded errors in the Fixes category. For how components, parameters and _Imports.razor fit together, see Blazor Components: Build Once, Use Everywhere.