Troubleshooting

Common Issues in Version 0.0.6

Authentication Problems

Cannot authenticate / API key rejected

Problem: Authentication fails with “Invalid API key” or similar errorsSolutions:

Verify API key is correct:
- Log into nextlovable.com
- Go to your dashboard
- Copy the API key exactly (no extra spaces)
Re-run authentication:
```
next-lovable auth
```
Paste the API key when prompted
Check account status:
- Ensure your account is active
- Verify you have credits remaining
- Check for any billing issues
Network connectivity:
```
curl -I https://api.nextlovable.com/health
```
Should return a 200 status code

Authentication token expired

Problem: Previously working authentication suddenly failsSolutions:

Re-authenticate:
```
next-lovable auth
```

Check token storage:

# Check if config exists
ls -la ~/.next-lovable/

Clear stored credentials and re-auth:

rm -rf ~/.next-lovable/
next-lovable auth

Network/firewall issues

Problem: Cannot connect to authentication serversSolutions:

Check firewall settings:
- Ensure outbound HTTPS (port 443) is allowed
- Whitelist *.nextlovable.com domains

Corporate proxy:

# Set proxy if needed
export HTTPS_PROXY=http://proxy.company.com:8080
next-lovable auth

Test connectivity:

ping api.nextlovable.com
curl -v https://api.nextlovable.com

Installation Issues

Command not found: next-lovable

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

Restart your terminal - This refreshes the PATH

Check installation location:

npm list -g next-lovable
which next-lovable

Verify 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

Use npx as alternative:
```
npx next-lovable@0.0.6 ./my-app
```

Version mismatch after installation

Problem: next-lovable --version shows wrong versionSolutions:

Uninstall and reinstall specific version:

npm uninstall -g next-lovable
npm install -g next-lovable@0.0.6

Clear npm cache:

npm cache clean --force
npm install -g next-lovable@0.0.6

Check for multiple installations:

# Find all installations
find / -name "next-lovable" 2>/dev/null
which -a next-lovable

Node.js version compatibility

Problem: Errors about Node.js version being incompatibleSolutions:

Check Node.js version:
```
node --version
```
Version 0.0.6 requires Node.js 16.x or higher
Update Node.js:
- Visit nodejs.org for official installer
- Or use nvm: nvm install 18 && nvm use 18

For Ubuntu/Debian:

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

Migration Issues

Source directory not recognized as React project

Problem: Tool doesn’t recognize your React projectSolutions:

Verify package.json exists and contains React:

cat package.json | grep -E "(react|react-dom|react-router)"

Check for required dependencies:

{
  "dependencies": {
    "react": "^16.8.0 || ^17.0.0 || ^18.0.0",
    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0",
    "react-router-dom": "^5.0.0 || ^6.0.0"
  }
}

Install missing dependencies:

npm install react react-dom react-router-dom

Check project structure: Ensure you have components or pages that use React Router

Migration fails with syntax errors

Problem: Migration stops due to syntax errors in source filesSolutions:

Fix syntax errors first:

# Check for TypeScript errors
npx tsc --noEmit

# Check for ESLint errors
npx eslint src/

Common syntax issues in v0.0.6:
- Missing semicolons
- Incorrect JSX syntax
- TypeScript type errors
- Import/export statement issues
Simplify complex patterns:
- Break down large components
- Remove experimental JavaScript features
- Fix any linting errors
Skip problematic files: Move complex files out temporarily, migrate, then manually port them

Target directory creation fails

Problem: Cannot create or write to target directorySolutions:

Check permissions:

ls -ld /path/to/parent/directory
touch /path/to/parent/directory/test-file

Use different location:

# Try in your home directory
next-lovable ./my-app ~/my-next-app

Check disk space:
```
df -h
```
Run with elevated permissions if needed:
```
sudo next-lovable ./my-app /opt/my-next-app
```

Migration incomplete / hangs

Problem: Migration process stops or hangs partway throughSolutions:

Check network connectivity:

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

Monitor system resources:

# Check memory usage
free -h

# Check CPU usage
top

Try smaller batches:
- Exclude large files temporarily
- Remove node_modules before migration
- Clear any build artifacts

Enable verbose logging:

DEBUG=next-lovable* next-lovable ./my-app

Kill and restart:

# Find and kill hung process
ps aux | grep next-lovable
kill -9 <process-id>

# Clean up and retry
rm -rf target-directory
next-lovable ./my-app ./clean-target

Post-Migration Issues

Generated Next.js app won't start

Problem: npm run dev fails with errorsSolutions:

Install dependencies:
```
cd migrated-project
npm install
```

Common dependency issues:

# Install missing Next.js types
npm install --save-dev @types/react @types/react-dom @types/node

# Update to compatible versions
npm install next@13 react@18 react-dom@18

Fix configuration issues:

# Check next.config.js for syntax errors
node -c next.config.js

# Regenerate if corrupted
rm next.config.js
# Create minimal config
echo "module.exports = {}" > next.config.js

Clear cache and rebuild:

rm -rf .next node_modules package-lock.json
npm install
npm run dev

Routing doesn't work correctly

Problem: Pages don’t load or routing is brokenSolutions:

Check App Router structure:

# Should have this structure
app/
├── layout.tsx
├── page.tsx (home page)
├── about/
│   └── page.tsx
└── contact/
    └── page.tsx

Verify page.tsx exports:

// Each page.tsx should export default
export default function PageName() {
  return <div>Content</div>;
}

Check for client component issues:

// Add 'use client' if component uses hooks or event handlers
'use client';

import { useState } from 'react';
// ... rest of component

Review navigation components: Ensure Link components use href instead of to

TypeScript errors after migration

Problem: Many TypeScript errors in migrated codeSolutions:

Update TypeScript configuration:

// tsconfig.json
{
  "compilerOptions": {
    "target": "es5",
    "lib": ["dom", "dom.iterable", "es6"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": false,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ]
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
  "exclude": ["node_modules"]
}

Install missing type definitions:

npm install --save-dev @types/react @types/react-dom @types/node

Fix common type issues:

// Add proper typing for components
interface Props {
  children: React.ReactNode;
}

export default function Component({ children }: Props) {
  return <div>{children}</div>;
}

Performance Issues

Migration is very slow

Problem: Migration takes an extremely long timeSolutions:

Check project size:

du -sh ./my-react-app
find ./my-react-app -name "*.tsx" -o -name "*.ts" | wc -l

Exclude unnecessary files:

# Remove build artifacts first
rm -rf node_modules dist build .next

Check network speed:

# Test upload speed to API
curl -w "@curl-format.txt" -s -o /dev/null https://api.nextlovable.com/health

System resources:
- Close other applications
- Check available RAM and CPU
- Use faster storage (SSD vs HDD)

High credit consumption

Problem: Migration uses more credits than expectedSolutions:

Check project complexity:
- Large projects consume more credits
- Complex routing patterns increase usage
- Many components increase processing
Use dry-run to estimate:
```
next-lovable ./my-app --dry-run
```
This shows estimated credit usage
Consider breaking down project:
- Migrate in smaller chunks
- Remove unused components
- Simplify complex routing
Upgrade to newer version: Version 0.0.7+ offers free single file conversions

Version 0.0.6 Specific Limitations

Known Limitations in v0.0.6:

All operations require authentication and credits
No single file conversion mode
Limited error recovery options
No granular transformation control
Older React Router patterns may not convert perfectly

Workarounds

For testing small changes: Use online converters or manual conversion
For better control: Upgrade to version 0.0.7+
For complex projects: Consider manual migration with v0.0.6 as reference

Getting Help

Debug Information

When reporting issues, include:

# Version information
next-lovable --version
node --version
npm --version

# System information
uname -a

# Project information
ls -la my-react-app/
cat my-react-app/package.json

# Error logs (if available)
cat ~/.next-lovable/logs/latest.log

Support Channels

GitHub Issues

Report bugs specific to v0.0.6

Discord Community

Get help from other users

Documentation

Browse v0.0.6 documentation

Upgrade Recommendation

Consider upgrading to version 0.0.7+ for:

Free single file conversions
Better error handling
More granular control
Improved performance
Enhanced CLI experience

Version 0.0.7+ Features

See what’s new in newer versions

Migration Guide

Learn how to use the latest version

Frequently Asked Questions

Can I use v0.0.6 without authentication?

Can I undo a migration?

Why does my complex routing not convert correctly?

How do I migrate from v0.0.6 to newer versions?

Report a Bug

Found a bug specific to version 0.0.6? Please report it with:

Version confirmation: next-lovable --version output
Clear description of the problem
Steps to reproduce the issue
Sample project that demonstrates the issue
Expected vs actual behavior
System information (OS, Node.js version, etc.)

Report on GitHub →

Getting Started

Commands

Guides

Common Issues in Version 0.0.6

Authentication Problems

Installation Issues

Migration Issues

Post-Migration Issues

Performance Issues

Version 0.0.6 Specific Limitations

Workarounds

Getting Help

Debug Information

Support Channels

GitHub Issues

Discord Community

Documentation

Upgrade Recommendation

Version 0.0.7+ Features

Migration Guide

Frequently Asked Questions

Report a Bug

Getting Started

Commands

Guides

​Common Issues in Version 0.0.6

​Authentication Problems

​Installation Issues

​Migration Issues

​Post-Migration Issues

​Performance Issues

​Version 0.0.6 Specific Limitations

​Workarounds

​Getting Help

​Debug Information

​Support Channels

GitHub Issues

Discord Community

Documentation

​Upgrade Recommendation

Version 0.0.7+ Features

Migration Guide

​Frequently Asked Questions

​Report a Bug

Common Issues in Version 0.0.6

Authentication Problems

Installation Issues

Migration Issues

Post-Migration Issues

Performance Issues

Version 0.0.6 Specific Limitations

Workarounds

Getting Help

Debug Information

Support Channels

Upgrade Recommendation

Frequently Asked Questions

Report a Bug