Vue "Failed to resolve component" - Fix in CI

By Kaveh Alemi·Latchkey

Vue could not find a component referenced in a template. With <script setup> it must be imported in the same file; otherwise it must be registered. A name or case mismatch breaks resolution too.

What this error means

The build warns/errors Failed to resolve component: <Name> and the component renders as a bare tag or fails strict checks.

vue

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

Diagnose it: is it resolution, transform, or memory?

Bundler failures in CI fall into three families and the error text often points at the wrong one. A module that resolves on your machine and not on the runner is nearly always case sensitivity or a missing optional dependency; a transform error is a config or version mismatch; and an unexplained kill with no stack is the out-of-memory reaper, not a build error at all.

Terminal

# 1. resolution: does the file exist with EXACTLY that case?
git ls-files | grep -i "the/imported/path"

# 2. transform: what versions is CI actually resolving?
npm ls webpack vite rollup esbuild typescript 2>/dev/null | head -20

# 3. memory: was it killed rather than failed?
#    exit 137 = SIGKILL (OOM). Nothing in the bundler log will explain it.
node --max-old-space-size=4096 node_modules/.bin/vite build

Common causes

Component not imported in script setup

With <script setup>, a component must be imported in the same SFC to be available in the template.

Name or case mismatch

The template tag does not match the registered/imported name, or case differs.

How to fix it

Import the component

Import it in the same SFC using script setup so it resolves in the template.

App.vue

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

Register globally if shared

For a widely used component, register it on the app instance.

main.ts

app.component('UserCard', UserCard);

Make the build reproducible before you debug it

Pin the Node major in setup-node and in engines. A bundler that resolves native bindings will pick a different prebuilt binary across majors.
Delete node_modules locally and reinstall from the lockfile before concluding the runner is at fault; most "works locally" reports are stale local state.
Set CI=true locally to reproduce. Several toolchains change behaviour under it, including treating warnings as errors.
Exit code 137 is an out-of-memory kill. Raise --max-old-space-size or move to a larger runner rather than searching the bundler config.

How to prevent it

Prefer explicit local imports in script setup over global registration.
Match template tag names and case to the imported component.

Frequently asked questions

What causes Vue "Failed to resolve component"?

There are 2 common causes: component not imported in script setup and name or case mismatch. With <script setup>, a component must be imported in the same SFC to be available in the template.

How do I fix Vue "Failed to resolve component"?

There are 2 fixes depending on which cause you have: import the component and register globally if shared. Work through them in order, since the first is the most common.

What does Vue "Failed to resolve component" actually mean?

The build warns/errors Failed to resolve component: <Name> and the component renders as a bare tag or fails strict checks.

How do I stop Vue "Failed to resolve component" happening again?

Prefer explicit local imports in script setup over global registration. The prevention section lists 2 changes that keep it from recurring.