Troubleshooting File Import Errors in Lovable Projects

Why file imports fail in Lovable projects

Lovable projects use TypeScript with Vite, which has a specific module resolution system. The @/ path alias is configured in both tsconfig.json and vite.config.ts to map to the src/ directory. When imports break, it is usually because the path does not match the actual file location, the export does not match the import syntax, or a circular dependency creates an undefined import. Case sensitivity is a subtle but common cause. macOS file systems are case-insensitive by default (UserProfile.tsx and userprofile.tsx are the same file), but Linux servers and GitHub are case-sensitive. An import that works locally can fail after deployment if the casing does not match exactly. Circular dependencies happen when file A imports from file B, which imports from file C, which imports from file A. This creates a loop that may result in some imports being undefined at runtime. The code does not produce a build error, but components fail to render.

• Import path does not match the actual file location — typo or wrong directory
• Default import used but the file has a named export, or vice versa
• File name casing in the import does not match the actual file name on disk
• Circular dependency chain where files import each other in a loop
• The @/ path alias is not configured or points to the wrong directory

Error messages you might see

Before you start

• A Lovable project with import errors in the console or build output
• Access to Dev Mode or the Lovable chat to see error messages
• The file tree visible in Dev Mode to verify file locations

How to fix it

// Fragile relative imports:
import Sidebar from "../../components/Sidebar";
import { useAuth } from "../hooks/useAuth";
import Dashboard from "./pages/Dashboard";

// Reliable @/ imports:
import Sidebar from "@/components/Sidebar";
import { useAuth } from "@/hooks/useAuth";
import Dashboard from "@/pages/Dashboard";

// File: src/components/UserProfile.tsx
export const UserProfile = () => { ... };
// Wrong: trying to use default import syntax
import UserProfile from "@/components/UserProfile";

// Named export → named import (with curly braces)
import { UserProfile } from "@/components/UserProfile";
// OR: change the export to default
export default UserProfile;
// Then: import UserProfile from "@/components/UserProfile";

// Circular dependency:
// UserProfile imports from useAuth
// useAuth imports from UserProfile
// Result: one of them is undefined at runtime

// Fix: extract shared types to a third file
// src/types/User.ts (new file with shared types)
export type User = { id: string; name: string; };
// src/hooks/useAuth.ts
import { User } from "@/types/User"; // No longer imports from UserProfile
// src/components/UserProfile.tsx
import { User } from "@/types/User"; // No longer imports from useAuth

// File on disk: src/components/UserProfile.tsx
// Import: wrong casing
import UserProfile from "@/components/userprofile";
// Works on macOS, FAILS on Linux/production

// File on disk: src/components/UserProfile.tsx
// Import: exact casing match
import UserProfile from "@/components/UserProfile";
// Works everywhere

Complete code example

1// All imports use @/ alias with exact casing
2import { useAuth } from "@/hooks/useAuth";
3import { Sidebar } from "@/components/layout/Sidebar";
4import { StatsCard } from "@/components/dashboard/StatsCard";
5import { OrdersTable } from "@/components/dashboard/OrdersTable";
6import { Button } from "@/components/ui/button";
7
8// Type imported from a shared types file (no circular dependency)
9import type { Order } from "@/types/Order";
10
11const Dashboard = () => {
12  const { user } = useAuth();
13
14  return (
15    <div className="flex min-h-screen">
16      <Sidebar />
17      <main className="flex-1 p-6 space-y-6">
18        <h1 className="text-2xl font-bold">
19          Welcome, {user?.name ?? "User"}
20        </h1>
21        <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
22          <StatsCard title="Total Orders" value="1,234" />
23          <StatsCard title="Revenue" value="$12,345" />
24          <StatsCard title="Customers" value="567" />
25        </div>
26        <OrdersTable />
27      </main>
28    </div>
29  );
30};
31
32export default Dashboard;

Best practices to prevent this

• Always use the @/ path alias instead of relative imports (../../) — it resolves from src/ consistently
• Match import syntax to export syntax: default exports without braces, named exports with braces
• Use PascalCase for component file names and match the casing exactly in import paths
• Extract shared types and utilities into separate files to avoid circular dependencies
• If an import fails, check Dev Mode file tree to verify the file exists at the expected path
• Add the .tsx extension explicitly in imports if auto-resolution fails (rarely needed in Vite)
• When renaming files, update all imports across the project in the same prompt
• Run a build check (ask Lovable to verify the project builds) to catch import errors early

Still stuck?

Copy one of these prompts to get a personalized, step-by-step explanation.

Related error patterns