If you've ever run AI-generated code from Antigravity only to be greeted by Cannot find module, Module not found, or Cannot use import statement, you're not alone. Package and module errors are among the most common frustrations when working with AI-assisted development tools.
The root cause is almost always the same: the AI doesn't have enough context about your project's dependencies. Antigravity's AI infers what packages and versions you're using from the files you have open and your project configuration. When that information is incomplete, it may generate code that references non-existent packages or uses outdated APIs.
Diagnosing the Error: Three Patterns
Before jumping to solutions, identify which pattern your error falls into:
Pattern 1: Import path errors
Error: Cannot find module './components/Button'
Error: Module not found: Can't resolve '@/lib/utils'
Pattern 2: Package not found
Error: Cannot find module 'zod'
Error: Cannot find module 'react-query'
Pattern 3: TypeScript declaration errors
Could not find a declaration file for module 'some-library'
Each pattern has a different root cause and a different fix, so always read the error message carefully before diving in.
Pattern 1: Fixing Import Path Errors
Path errors usually mean the AI doesn't know your project's directory structure or path alias configuration. This is especially common in projects that use @/ as an alias for the src/ directory.
Check your path alias configuration
# Verify path aliases in tsconfig.json
cat tsconfig.json | grep -A 10 '"paths"'If you see something like this, the AI needs to be made aware of it:
{
"compilerOptions": {
"paths": {
"@/*": ["./src/*"]
}
}
}The fix: keep tsconfig.json open
When tsconfig.json is open in the editor, Antigravity automatically picks up the path alias configuration. For chat-based requests, be explicit:
This project uses @/ as an alias for src/. tsconfig.json is open.
Please create the following component.
Pattern 2: Package Not Found Errors
This typically means one of two things: the package isn't in package.json, or node_modules is in a broken state.
Step 1: Check package.json
# See if the package is listed
cat package.json | grep "zod"If it's missing, install it:
npm install zod
# or
pnpm add zodStep 2: Rebuild node_modules
If the package is in package.json but the error persists, a corrupted node_modules directory is likely the culprit. This is more common than you'd think:
rm -rf node_modules
npm installStep 3: Tell the AI what packages you have
To prevent the AI from generating code that uses packages you haven't installed, add a section to your .antigravity/rules.md or AGENTS.md:
## Package Constraints
Always check package.json before suggesting new dependencies.
Prefer solutions using existing packages. If a new package is genuinely required,
mention it explicitly and include the install command.For more on setting up custom rules, see the Antigravity Custom Rules Configuration Guide.
Pattern 3: TypeScript Declaration Errors
Could not find a declaration file for module 'xxx' means TypeScript type definitions are missing for that package.
Install the type definitions
npm install --save-dev @types/node
npm install --save-dev @types/reactMost modern packages bundle their own types, but older or niche packages may require separate @types/ packages.
Quick fix when no types are available
If you need to unblock yourself while proper type definitions aren't available, create a declarations.d.ts file:
// src/declarations.d.ts
declare module 'some-library' {
export function someFunction(arg: string): void;
}Tell Antigravity: "Add a type declaration to declarations.d.ts for temporary compatibility with this module." It will generate the appropriate declaration for your use case.
Handling Version Conflict Errors
Version conflicts occur when multiple packages require incompatible versions of the same dependency:
npm error ERESOLVE unable to resolve dependency tree
npm error Could not resolve dependency:
npm error peer react@"^17.0.0" from some-package@2.0.0
Diagnose first
npm ls react
# or clean up duplicates
npm dedupeLet Antigravity diagnose it
The most efficient approach is to paste the full error message into Antigravity's chat with package.json open:
I'm getting the following npm error. Please look at package.json
and suggest how to resolve this dependency conflict.
[paste error message here]
With package.json in context, the AI can reason about the full dependency tree and suggest an appropriate resolution strategy.
A Common Pitfall: AI Using Outdated API Syntax
Sometimes the package is found but the generated code still throws errors. This often happens when the AI uses syntax from an older API version.
TanStack Query is a classic example: the API changed substantially between v4 and v5. If you have v5 installed but the AI writes v4-style code, you'll get runtime errors even though the package itself is present.
Always specify your version
# Check what version you actually have installed
npm list @tanstack/react-queryThen include the version in your prompt:
I'm using @tanstack/react-query v5.0.0.
Please implement the following using the v5 API.
Long-Term Fix: Use AGENTS.md to Lock In Context
Specifying versions and package constraints in every prompt is tedious. The better solution is to document your project's stack in AGENTS.md at the project root. Antigravity reads this file automatically, giving the AI the context it needs without any extra prompting.
# Project Tech Stack
## Key Packages
- Next.js: 16.x (App Router)
- TypeScript: 5.x (strict mode enabled)
- @tanstack/react-query: 5.x
- zod: 3.x
- Prisma: 5.x
## Path Aliases
@/ → src/
## Rules
- Never add packages without explicit user approval
- Always use packages listed in package.jsonWith this in place, module and package errors become the exception rather than the rule. For build and deployment errors that may follow, see the Antigravity Build & Deploy Error Troubleshooting guide.
Quick Diagnostic Checklist
When a module error appears, run through this checklist in order:
- Is the package listed in
package.json? - Does
node_modulesexist? If not, runnpm install - Are path aliases correctly configured in
tsconfig.json? - Does the version of the package installed match what the AI is generating code for?
- Is your tech stack documented in
AGENTS.md?
Antigravity's AI is capable, but it can only work with the information it has access to. Documenting your project's dependencies and version constraints in AGENTS.md is the single most effective step you can take to reduce module errors. Start there, and you'll notice a significant improvement right away.