Skip to main content
RapidDev - Software Development Agency
cursor-tutorial

Why Cursor imports files that do not exist

Cursor frequently imports modules, functions, and types that do not exist in your project because it hallucinates based on common naming patterns. By referencing your package.json with @file, adding import validation rules to .cursorrules, and running TypeScript compilation checks after generation, you catch and fix phantom imports before they cause runtime errors.

What you'll learn

  • Why Cursor imports files that do not exist
  • How to prevent hallucinated imports with .cursorrules
  • How to validate imports after Cursor generates code
  • How to provide better context so imports are accurate
Book a free consultation
4.9Clutch rating
600+Happy partners
17+Countries served
190+Team members
Beginner7 min read10-15 minCursor Free+, TypeScript/JavaScript projectsMarch 2026RapidDev Engineering Team
TL;DR

Cursor frequently imports modules, functions, and types that do not exist in your project because it hallucinates based on common naming patterns. By referencing your package.json with @file, adding import validation rules to .cursorrules, and running TypeScript compilation checks after generation, you catch and fix phantom imports before they cause runtime errors.

Fixing phantom imports in Cursor-generated code

Cursor's AI models predict likely import paths based on naming patterns, not your actual file system. This causes imports of non-existent files, wrong package names, and incorrect relative paths. This tutorial teaches prevention, detection, and fixing strategies.

Prerequisites

  • Cursor installed with a TypeScript or JavaScript project
  • TypeScript compiler configured (tsconfig.json)
  • package.json with your project dependencies
  • Familiarity with Cursor Chat (Cmd+L) and Cmd+K

Step-by-step guide

1

Add import validation rules to .cursor/rules

Create rules that guide Cursor to use only verified import paths. Reference your project structure and installed packages.

.cursor/rules/imports.mdc
1---
2description: Import validation rules
3globs: "src/**/*.ts,src/**/*.tsx"
4alwaysApply: true
5---
6
7## Import Rules
8- ONLY import from packages listed in package.json
9- ONLY import from files that exist in the project
10- Use @/ alias for src/ imports (configured in tsconfig)
11- NEVER guess at import paths ask if unsure
12- NEVER import from packages not in package.json
13- Check @package.json before using any third-party import
14
15## Known Project Structure
16- @/components/ React components
17- @/hooks/ custom hooks
18- @/lib/ utility functions
19- @/types/ TypeScript types
20- @/services/ API service classes
21- @/config/ configuration modules
22
23## Common False Imports to AVOID
24- Do NOT import from '@/utils' (use @/lib instead)
25- Do NOT import from 'lodash' (not installed, use native)
26- Do NOT import from '@/api' (use @/services instead)

Expected result: Cursor uses verified import paths and avoids hallucinating non-existent modules.

2

Reference package.json and tsconfig in prompts

Include @package.json when asking Cursor to generate code that needs external imports. This gives the AI visibility into what packages are actually installed.

Cursor Chat prompt
1// Cursor Chat prompt (Cmd+L):
2// @package.json @tsconfig.json
3// Generate a date formatting utility at src/lib/dates.ts.
4// Only use packages that are in our package.json.
5// If a package is needed but not installed, tell me
6// instead of importing it.
7
8// This prevents Cursor from importing moment, luxon, or
9// other date libraries that are not in your dependencies.

Pro tip: Adding 'If a package is needed but not installed, tell me instead of importing it' forces Cursor to flag missing dependencies rather than silently importing them.

Expected result: Cursor only imports from installed packages and flags missing dependencies.

3

Run TypeScript compiler to catch phantom imports

After Cursor generates code, run the TypeScript compiler in no-emit mode to catch any import errors. This is the fastest way to find non-existent imports.

Terminal
1// Terminal:
2npx tsc --noEmit
3
4// Common errors from phantom imports:
5// Cannot find module '@/utils/helpers' or its corresponding type declarations
6// Module '@/api/userClient' has no exported member 'fetchUser'
7// Cannot find module 'lodash/debounce'
8
9// Paste errors into Cursor Chat:
10// @package.json These import errors appeared after your
11// last generation. Fix them using only packages in our
12// package.json and files that exist in our project.

Expected result: TypeScript compiler catches all phantom imports so you can fix them before runtime.

4

Fix phantom imports with Cursor

Paste the TypeScript errors back into Cursor Chat and ask it to fix the imports. Reference the files that DO exist so Cursor can find the correct paths.

Cursor Chat prompt
1// Cursor Chat prompt (Cmd+L):
2// @src/lib/ @package.json
3// Fix these import errors:
4// 1. '@/utils/helpers' does not exist → find the correct
5// path in src/lib/ that has the needed function
6// 2. 'lodash/debounce' is not installed → implement a
7// simple debounce function in src/lib/debounce.ts
8// 3. '@/api/userClient' does not exist → use the existing
9// @/services/UserService instead

Expected result: All phantom imports replaced with correct paths to existing files and packages.

5

Prevent phantom imports in Composer sessions

When using Composer Agent mode, which creates multiple files, add extra context upfront to prevent phantom imports across the generated files.

Cursor Composer prompt
1// Composer prompt (Cmd+I):
2// @package.json @src/lib/ @src/services/ @src/types/
3// Generate a new notification module with:
4// - src/services/NotificationService.ts
5// - src/hooks/useNotifications.ts
6// - src/types/notification.ts
7//
8// IMPORTANT: Only import from:
9// - Packages in package.json
10// - Files that already exist (referenced above)
11// - Files you are creating in this session
12// Do NOT import from any path that does not exist.

Expected result: Multiple generated files with only valid imports to existing code and packages.

Complete working example

.cursor/rules/imports.mdc
1---
2description: Import validation and path rules
3globs: "src/**/*.{ts,tsx}"
4alwaysApply: true
5---
6
7## Valid Import Sources
81. Installed packages (listed in package.json dependencies)
92. Existing project files (verified by file system)
103. Files being created in the current generation
11
12## Project Path Aliases
13- @/ src/ (configured in tsconfig.json paths)
14- Use @/ for all internal imports
15- NEVER use relative paths that go up more than 2 levels (../../..)
16
17## Project Directory Map
18```
19src/
20 components/ React components (*.tsx)
21 hooks/ Custom hooks (use*.ts)
22 lib/ Utility functions
23 services/ API and business logic classes
24 types/ TypeScript interfaces and types
25 config/ Configuration modules
26 middleware/ Express/API middleware
27```
28
29## Import Validation Rules
30- Check @package.json before importing any npm package
31- If a package is needed but not installed, TELL the user
32- NEVER silently import non-existent packages
33- NEVER guess at file paths reference @src/ to see what exists
34- Use 'import type' for type-only imports
35
36## Commonly Hallucinated Imports (DO NOT USE)
37- '@/utils/*' use '@/lib/*' instead
38- '@/api/*' use '@/services/*' instead
39- '@/store/*' use '@/hooks/*' or '@/contexts/*'
40- 'lodash' not installed, use native JS
41- 'moment' not installed, use date-fns or native Date

Common mistakes

Why it's a problem: Cursor importing from '@/utils' when the directory is called '@/lib'

How to avoid: Add your actual directory names to .cursorrules under 'Project Directory Map'. List common aliases to avoid.

Why it's a problem: Cursor importing packages not in package.json

How to avoid: Reference @package.json in every prompt. Add 'ONLY import packages in package.json' to your rules.

Why it's a problem: Not running TypeScript compiler after generation

How to avoid: Run npx tsc --noEmit after every Cursor generation session. Add it to your pre-commit hook.

Best practices

  • Reference @package.json when generating code that needs external imports
  • Add your project directory map to .cursorrules so Cursor knows actual paths
  • Run npx tsc --noEmit after every Cursor generation session
  • List commonly hallucinated imports in .cursorrules with correct alternatives
  • Use 'tell me if a package is needed but not installed' in prompts
  • Reference @src/ folders when using Composer to generate multiple files
  • Add TypeScript compilation to your pre-commit hook to catch phantom imports

Still stuck?

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

ChatGPT Prompt

I have a TypeScript project with src/lib for utilities, src/services for API classes, and src/types for interfaces. Cursor keeps importing from '@/utils' which does not exist. Create .cursorrules that: maps correct directory names, lists common hallucinated paths with corrections, and requires checking package.json before external imports.

Cursor Prompt

In Cursor Chat (Cmd+L): @package.json @src/ These TypeScript errors appeared: 'Cannot find module @/utils/helpers'. The correct path is @/lib/. Fix all imports in the generated files. Only use packages from package.json and paths that exist in src/.

Frequently asked questions

Why does Cursor import files that do not exist?

Cursor predicts import paths based on naming patterns, not your file system. If common patterns (utils, api, store) differ from your structure (lib, services, contexts), Cursor will hallucinate the common names.

Can Cursor check if imports are valid?

Not automatically during generation. Use Ask mode to verify: '@codebase Check if all imports in this file resolve to existing modules.' Or run npx tsc --noEmit for definitive validation.

How do I handle imports from packages I plan to install?

Install the package first (npm install), then generate code. Or tell Cursor: 'I will install axios. Generate code using axios with proper imports.' Then install before compiling.

Will .cursorrules prevent all phantom imports?

Rules significantly reduce them but cannot eliminate them entirely, especially in long sessions. Always run TypeScript compilation as a safety net.

Can I make Cursor aware of my full file tree?

Yes. Use @folder to reference entire directories, giving Cursor visibility into what exists. For large projects, use .cursorignore to exclude irrelevant directories and keep indexing focused.

RapidDev

Talk to an Expert

Our team has built 600+ apps. Get personalized help with your project.

Book a free consultation

Need help with your project?

Our experts have built 600+ apps and can accelerate your development. Book a free consultation — no strings attached.

Book a free consultation

We put the rapid in RapidDev

Need a dedicated strategic tech and growth partner? Discover what RapidDev can do for your business! Book a call with our team to schedule a free, no-obligation consultation. We'll discuss your project and provide a custom quote at no cost.