Angular Basics: Troubleshooting Unknown Element Errors

Error NG8001 flags when there is an unknown element or component in your Angular code. Here are some of causes, solutions and steps to prevent such an error.

With the growing complexity of today’s web pages, new technologies have emerged. One such technology is Angular JS, a popular framework for developing single-page applications.

Despite this, Angular errors can be difficult to debug and resolve. In this post we will be trying to troubleshoot one of the most common errors you can come across while using Angular—an error called “‘X’ is not a known element,” also called Angular Error NG8001. It is especially confusing because this error can come up in different ways and with different causes. This article provides a detailed explanation of all these causes and also how to fix them.

What Is Angular Error NG8001?

An Angular error is an error that occurs during the execution of an Angular application. There are a variety of reasons why an Angular error may occur, ranging from syntax errors in the Angular code to errors in the underlying operating system or hardware. This can make Angular errors difficult to debug and resolve.

The “Angular error NG8001: Unknown HTML element or component” error is a run-time error that occurs when the Angular compiler encounters an unexpected token. This can happen when the Angular template contains a syntax error, or when the Angular compiler encounters a TypeScript error.

The error will look like this in the compiler:

NG0304: '${tagName}' is not a known element: ....

The Causes of the Angular Error NG8001

There are several potential reasons for the Angular error NG8001. One possibility is that the Angular CLI is not installed correctly. Another possibility is that the Angular project is not set up correctly, or that there is an error in the project configuration. It is also possible that the error is caused by a conflict between different versions of Angular.

How To Fix Angular Error NG8001

Example 1: Error NG8001: Router-Outlet Is Not a Known Element

Error in src/app/components/layout/layout.component.html:8:17 - error NG8001: router-outlet is not a known element:

1. If router-outlet is an Angular component, then verify that it is part of this module.
2. If router-outlet is a web component, then add CUSTOM_ELEMENTS_SCHEMA to the @NgModule.schemas of this component to suppress this message.

Code in my app.component:

<router-outlet></router-outlet>

Solution:
The first thing I did was to import RouterModule on the external module, like this:

@NgModule({
    declarations:[
        AlertsComponent,
        FooterComponent,
        LogoutComponent,
        MessageComponent,
        SearchComponent,
        SidebarComponent,
        TopbarComponent,
        UserInfoComponent,
        LayoutComponent,
    ],
    imports:[
        RouterModule
    ]
})
export class LayoutModule {}

Then I imported the module on app.module.ts:

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    AppRoutingModule,
    BrowserModule,
    LayoutModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Example 2: NG8001: Mat-Spinner Is Not a Known Element

Error NG8001: mat-spinner is not a known element:

1. If mat-spinner is an Angular component, then verify that it is part of this module.
2. If mat-spinner is a web component, then add CUSTOM_ELEMENTS_SCHEMA to the @NgModule.schemas of this component to suppress this message. ("[ERROR ->]<mat-spinner></mat-spinner>")

Code in my app.module.ts:

@NgModule({
  imports: [
    BrowserModule,
    ReactiveFormsModule
  ],
  declarations: [
    AppComponent
  ],
  bootstrap: [ AppComponent ]
})
export class AppModule { }

Code in my app.component:

<mat-spinner></mat-spinner>

Solution:
In the above example you are missing the MatProgressSpinnerModule in your AppModule imports. It should look like below and then will work:

@NgModule({
  imports: [
    BrowserModule,
    ReactiveFormsModule,
    MatProgressSpinnerModule
  ],
  declarations: [
    AppComponent
  ],
  bootstrap: [ AppComponent ]
})
export class AppModule { }

Example 3: Error NG8001: Mat-Card Is Not a Known Element:

Error: mat-card is not a known element:

1. If mat-card is an Angular component, then verify that it is part of this module.
2. If mat-card is a web component then add CUSTOM_ELEMENTS_SCHEMA to the @NgModule.schemas of this component to suppress this message. ("[ERROR ->]<mat-card> </mat-card>”)

Code in my app.module.ts:

import { BrowserModule } from "@angular/platform-browser";
import { BrowserAnimationsModule } from "@angular/platform-browser/animations";
import { LOCALE_ID, NgModule } from "@angular/core";
import { HttpClientModule, HTTP_INTERCEPTORS } from "@angular/common/http";
import { AppRoutingModule } from "./app-routing.module";
import { AppComponent } from "./app.component";
import {
  MatButtonModule,
  MatFormFieldModule,
  MatIconModule,
  MatInputModule,
  MatListModule,
  MatSelectModule,
  MatSidenavModule,
  MatCardModule,
  MatTableModule
} from "@angular/material";

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    BrowserAnimationsModule,
    AppRoutingModule,
    HttpClientModule,
    MatButtonModule,
    MatFormFieldModule,
    MatIconModule,
    MatListModule,
    MatInputModule,
    MatSelectModule,
    MatSidenavModule,
    MatCardModule,
    MatTableModule
  ],....
})
export class AppModule {}

I am trying to use employees.component.html in my src/app/employees but it’s not working.

<mat-card></mat-card>

Solution:
Declare EmployeesComponent in the same module as where you imported the MatCardModule like this:

declarations: [
    EmployeesComponent
],
imports: [
    MatCardModule
]

Try importing MatCardModule as:

import { MatCardModule } from '@angular/material/card';

More Troubleshooting Techniques That Can Help You

Upgrade to AngularJS Version 1.3 or Higher

If you are using an older version of Angular, sometimes you can solve the error ng8001 by upgrading to the latest version. This error is caused by a conflict between Angular and the new version of jQuery. By upgrading to the latest version of Angular, you can resolve this conflict and avoid the error.

Upgrade Angular CLI and Package Manager

If you’re seeing the error “NG8001” in your Angular project, it’s likely that you’re using a newer version of the Angular CLI than is supported by the version of Angular you’re using. To fix this, you can either downgrade the Angular CLI to an older version or upgrade Angular to a newer version.

Use Ahead-of-Time (AoT) Compilation and Source Maps

If you’re seeing the error message “Angular error NG8001” and you’re not sure where the error is, you can use the Angular CLI to help find it. To do this, run the following command:

ng serve --aot --source-map

This will compile your Angular application with Ahead-of-Time (AoT) compilation and source maps. With AoT compilation, the Angular compiler will find and report any errors in your application.

With source maps, you will be able to see the original source code (before it was compiled to JavaScript) which will make it easier to find and fix the error. This command will only work on Angular 13 or later.

How To Prevent ‘X Is Not a Known Element’ Error (NG8001)

These are the five steps I perform when I get such an error, and implementing these steps as you write your program can help you prevent this error from occurring.

1. Make sure the name is correct. (Also check the selector defined in the component.)
2. Declare the component in a module.
3. If it is in another module, export the component.
4. If it is in another module, import that module.
5. Restart the terminal and try again.

Note: When the error occurs during unit testing, make sure you declared the component.

Final Words

With this troubleshooting piece, we hope that you are able to avoid this error and prevent it from hindering your important projects. If you have other questions or concerns, please reach out anytime.