Troubleshooting

Common Issues

Installation Problems

Command not found: next-lovable

Problem: After installation, running next-lovable shows “command not found”Solutions:

Restart your terminal - This refreshes the PATH
Check if npm global bin is in PATH:
```
npm config get prefix
echo $PATH
```
The npm prefix path should be in your PATH

Add npm global bin to PATH (if missing):

# For bash/zsh
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For fish shell
set -U fish_user_paths (npm config get prefix)/bin $fish_user_paths

Use npx as alternative:

npx next-lovable convert MyComponent.tsx

Permission denied errors

Problem: Getting permission errors during global installationSolutions:

Configure npm to use a different directory (recommended):

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g next-lovable

Use sudo (less secure):
```
sudo npm install -g next-lovable
```
Use a Node.js version manager like nvm, which handles permissions better

Node.js version incompatibility

Problem: Errors about Node.js version being too oldSolutions:

Check your Node.js version:
```
node --version
```
You need 18.x or higher
Update Node.js:
- Visit nodejs.org for official installer
- Or use a version manager like nvm:
  nvm install node # installs latest nvm use node

For Ubuntu/Debian:

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs

Conversion Issues

File not found or cannot read file

Problem: Error reading the file you’re trying to convertSolutions:

Check file path is correct:
```
ls -la src/components/MyComponent.tsx
```

Use absolute path:

next-lovable convert /full/path/to/MyComponent.tsx

Check file permissions:
```
chmod 644 MyComponent.tsx
```
Make sure file extension is supported:
- Supported: .tsx, .ts, .jsx, .js
- Not supported: .vue, .svelte, etc.

Syntax error in component

Problem: Tool reports syntax errors in your React componentSolutions:

Fix syntax errors first:

# Use your editor's linter or
npx tsc --noEmit MyComponent.tsx  # for TypeScript
npx eslint MyComponent.tsx        # for ESLint

Check for unsupported syntax:
- Experimental JavaScript features
- Non-standard JSX patterns
- Mixing TypeScript and JavaScript incorrectly
Simplify complex patterns:
- Extract complex logic to separate functions
- Break down large components
- Remove experimental decorators

Conversion results look wrong

Problem: The converted code doesn’t work as expectedSolutions:

Use dry-run first to preview:

next-lovable convert MyComponent.tsx --dry-run --show-diff

Apply transformations incrementally:

# Test each transformation separately
next-lovable convert MyComponent.tsx --transform router --dry-run
next-lovable convert MyComponent.tsx --transform client --dry-run

Check for complex routing patterns:
- Dynamic routes with complex parameters
- Nested routing with custom logic
- Route guards and middleware
Manual review needed for:
- Custom hooks that depend on React Router internals
- Complex state management patterns
- Third-party library integrations

'use client' directive not added when needed

Problem: Component uses client-side features but no directive was addedSolutions:

Manually apply client transformation:

next-lovable convert MyComponent.tsx --transform client

Check for these patterns that need ‘use client’:
- React hooks (useState, useEffect, etc.)
- Event handlers (onClick, onChange, etc.)
- Browser APIs (window, document, localStorage)
- Third-party client libraries

Add manually if needed:

'use client';

import React from 'react';
// rest of component

Migration Issues

Authentication failed

Problem: Cannot authenticate for full project migrationSolutions:

Check your API key:
```
next-lovable auth --check
```
Re-authenticate:
```
next-lovable auth
```
Enter your API key from nextlovable.com dashboard
Verify account status:
- Log into nextlovable.com
- Check if your account is active
- Verify you have credits remaining

Check network connection:

curl -I https://api.nextlovable.com/health

Migration fails partway through

Problem: Full project migration stops with errorsSolutions:

Use dry-run first:
```
next-lovable migrate ./my-app --dry-run
```
This identifies issues before making changes
Check for blocking issues:
- Syntax errors in source files
- Permission issues with target directory
- Insufficient disk space
- Network connectivity issues

Try incremental approach:

# Convert critical files individually first
next-lovable convert src/App.tsx
next-lovable convert src/components/Navigation.tsx
# Then run migration

Clean up and retry:

rm -rf target-directory
next-lovable migrate ./my-app ./clean-target --yes

Generated Next.js project won't start

Problem: The migrated project has errors when running npm run devSolutions:

Install dependencies:

cd migrated-project
npm install
# or
yarn install

Check Next.js configuration:
```
cat next.config.js
```
Look for any obvious configuration issues
Review error messages:
- Missing dependencies
- Import path issues
- TypeScript errors
- CSS/styling conflicts

Common fixes:

# Update Next.js to latest
npm install next@latest react@latest react-dom@latest

# Fix TypeScript issues
npm install --save-dev @types/react @types/react-dom

# Clear Next.js cache
rm -rf .next
npm run dev

Performance Issues

Conversion is very slow

Problem: Converting files or projects takes a long timeSolutions:

Check file size:
```
ls -lh MyComponent.tsx
```
Very large files (>100KB) take longer
Break down large files:
- Split large components into smaller ones
- Extract utility functions
- Separate types and interfaces
Check network (for migrations):
- Full migrations require API calls
- Slow internet affects migration speed
- Use --dry-run for local-only testing
System resources:
- Close other applications
- Check available RAM and CPU
- Use faster storage (SSD vs HDD)

High memory usage

Problem: Tool uses too much memory during conversionSolutions:

Process files individually:

# Instead of: next-lovable convert src/**/*.tsx
# Use: find src -name "*.tsx" -exec next-lovable convert {} \;

Close other applications to free up memory

Increase Node.js memory limit:

node --max-old-space-size=4096 $(which next-lovable) convert MyComponent.tsx

Break down large projects into smaller batches

Getting Help

Debug Information

When reporting issues, include this information:

# Next-lovable version
next-lovable --version

# Node.js version
node --version

# npm version
npm --version

# Operating system
uname -a  # Linux/macOS
# or
systeminfo  # Windows

# File you're trying to convert (if small)
cat MyComponent.tsx

Log Files

Enable verbose logging for detailed error information:

next-lovable convert MyComponent.tsx --verbose

Support Channels

GitHub Issues

Report bugs and feature requests

Discord Community

Get help from the community

Documentation

Browse all documentation

Frequently Asked Questions

Can I undo a conversion?

Why wasn't my complex routing converted?

Will this work with my custom webpack config?

How do I handle custom hooks that use React Router?

Custom hooks using React Router internals need manual conversion:

// Before
const useAuth = () => {
  const navigate = useNavigate();
  // ... logic
};

// After (manual conversion needed)
'use client';
const useAuth = () => {
  const router = useRouter();
  // ... updated logic
};

Report a Bug

Found a bug? Please report it with:

Clear description of the problem
Steps to reproduce the issue
Expected vs actual behavior
Sample code that causes the issue
System information (OS, Node.js version, etc.)

Report on GitHub →

Getting Started

Commands

Guides

Common Issues

Installation Problems

Conversion Issues

Migration Issues

Performance Issues

Getting Help

Debug Information

Log Files

Support Channels

GitHub Issues

Discord Community

Documentation

Frequently Asked Questions

Report a Bug

Getting Started

Commands

Guides

​Common Issues

​Installation Problems

​Conversion Issues

​Migration Issues

​Performance Issues

​Getting Help

​Debug Information

​Log Files

​Support Channels

GitHub Issues

Discord Community

Documentation

​Frequently Asked Questions

​Report a Bug

Common Issues

Installation Problems

Conversion Issues

Migration Issues

Performance Issues

Getting Help

Debug Information

Log Files

Support Channels

Frequently Asked Questions

Report a Bug