The Problem

Vue warns when it encounters a tag in a template that does not match any registered component or known HTML element. This happens when you forget to import and register a component.

Symptoms

  • Console warning: "Failed to resolve component: MyComponent"
  • Component renders as a plain HTML element (custom element) with no content
  • Works in some files but not others
  • Warning only appears in development mode

Real Error Message

bash
[Vue warn]: Failed to resolve component: UserCard
If this is a native custom element, make sure to exclude it from component
resolution via compilerOptions.isCustomElement.

Common Causes

Cause 1: Forgetting to Import the Component

```vue <!-- WRONG: UserCard used but never imported --> <template> <UserCard :user="user" /> </template>

<script setup> // Missing: import UserCard from './UserCard.vue' defineProps({ user: Object }); </script> ```

Cause 2: Typo in Component Name

```vue <script setup> import UsrCard from './UserCard.vue'; // Typo! </script>

<template> <UserCard :user="user" /> <!-- Tag doesn't match import name --> </template> ```

Cause 3: Global Registration Missing (Options API)

```javascript // main.js import { createApp } from 'vue'; import App from './App.vue';

// WRONG: Component used globally but never registered const app = createApp(App); app.component('UserCard', UserCard); // Must import first! app.mount('#app'); ```

How to Fix It

Fix 1: Import and Use in Script Setup (Vue 3)

```vue <script setup> import UserCard from './UserCard.vue';

defineProps({ user: Object }); // UserCard is automatically available in template </script>

<template> <UserCard :user="user" /> </template> ```

Fix 2: Local Registration (Options API)

```vue <script> import UserCard from './UserCard.vue';

export default { components: { UserCard }, data() { return { user: null }; } }; </script> ```

Fix 3: Global Registration for Reusable Components

```javascript // main.js import { createApp } from 'vue'; import App from './App.vue'; import UserCard from './components/UserCard.vue'; import BaseButton from './components/BaseButton.vue';

const app = createApp(App);

// Prefix reusable components with 'Base' app.component('BaseButton', BaseButton); app.component('UserCard', UserCard);

app.mount('#app'); ```

Fix 4: Configure Custom Elements (for Web Components)

javascript
// vite.config.js
export default defineConfig({
  plugins: [
    vue({
      template: {
        compilerOptions: {
          isCustomElement: tag => tag.startsWith('ion-') || tag.startsWith('wc-')
        }
      }
    })
  ]
});

This tells Vue to ignore certain tags instead of trying to resolve them as components.