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
Add import validation rules to .cursor/rules
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.
1---2description: Import validation rules3globs: "src/**/*.ts,src/**/*.tsx"4alwaysApply: true5---67## Import Rules8- ONLY import from packages listed in package.json9- ONLY import from files that exist in the project10- Use @/ alias for src/ imports (configured in tsconfig)11- NEVER guess at import paths — ask if unsure12- NEVER import from packages not in package.json13- Check @package.json before using any third-party import1415## Known Project Structure16- @/components/ — React components17- @/hooks/ — custom hooks18- @/lib/ — utility functions19- @/types/ — TypeScript types20- @/services/ — API service classes21- @/config/ — configuration modules2223## Common False Imports to AVOID24- 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.
Reference package.json and tsconfig in prompts
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.
1// Cursor Chat prompt (Cmd+L):2// @package.json @tsconfig.json3// 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 me6// instead of importing it.78// This prevents Cursor from importing moment, luxon, or9// 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.
Run TypeScript compiler to catch phantom imports
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.
1// Terminal:2npx tsc --noEmit34// Common errors from phantom imports:5// Cannot find module '@/utils/helpers' or its corresponding type declarations6// Module '@/api/userClient' has no exported member 'fetchUser'7// Cannot find module 'lodash/debounce'89// Paste errors into Cursor Chat:10// @package.json These import errors appeared after your11// last generation. Fix them using only packages in our12// package.json and files that exist in our project.Expected result: TypeScript compiler catches all phantom imports so you can fix them before runtime.
Fix phantom imports with Cursor
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.
1// Cursor Chat prompt (Cmd+L):2// @src/lib/ @package.json3// Fix these import errors:4// 1. '@/utils/helpers' does not exist → find the correct5// path in src/lib/ that has the needed function6// 2. 'lodash/debounce' is not installed → implement a7// simple debounce function in src/lib/debounce.ts8// 3. '@/api/userClient' does not exist → use the existing9// @/services/UserService insteadExpected result: All phantom imports replaced with correct paths to existing files and packages.
Prevent phantom imports in Composer sessions
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.
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.ts5// - src/hooks/useNotifications.ts6// - src/types/notification.ts7//8// IMPORTANT: Only import from:9// - Packages in package.json10// - Files that already exist (referenced above)11// - Files you are creating in this session12// 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
1---2description: Import validation and path rules3globs: "src/**/*.{ts,tsx}"4alwaysApply: true5---67## Valid Import Sources81. Installed packages (listed in package.json dependencies)92. Existing project files (verified by file system)103. Files being created in the current generation1112## Project Path Aliases13- @/ → src/ (configured in tsconfig.json paths)14- Use @/ for all internal imports15- NEVER use relative paths that go up more than 2 levels (../../..)1617## Project Directory Map18```19src/20 components/ → React components (*.tsx)21 hooks/ → Custom hooks (use*.ts)22 lib/ → Utility functions23 services/ → API and business logic classes24 types/ → TypeScript interfaces and types25 config/ → Configuration modules26 middleware/ → Express/API middleware27```2829## Import Validation Rules30- Check @package.json before importing any npm package31- If a package is needed but not installed, TELL the user32- NEVER silently import non-existent packages33- NEVER guess at file paths — reference @src/ to see what exists34- Use 'import type' for type-only imports3536## Commonly Hallucinated Imports (DO NOT USE)37- '@/utils/*' → use '@/lib/*' instead38- '@/api/*' → use '@/services/*' instead 39- '@/store/*' → use '@/hooks/*' or '@/contexts/*'40- 'lodash' → not installed, use native JS41- 'moment' → not installed, use date-fns or native DateCommon 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.
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.
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.
Talk to an Expert
Our team has built 600+ apps. Get personalized help with your project.
Book a free consultation