Skip to main content

Troubleshooting

Having problems? Don't worry! Here are the most common issues and solutions. Most problems can be answered here.

Quick Diagnosis​

Before diving into troubleshooting, try these general solutions first:

  1. Check terminal environment (Windows users recommended)
    • Windows: Recommend using Git Bash, CMD/PowerShell only has simple compatibility
    • macOS/Linux: Any terminal works
  2. Check Node.js version: node --version (needs >= 20)
  3. View CLI logs: lovrabet logs
  4. Re-login: lovrabet auth
  5. Check configuration: lovrabet config list

Environment Compatibility Issues​

💻 Windows Terminal Environment Issues​

Symptoms:

  • Some commands execute abnormally in Windows CMD
  • Encountering path or environment variable issues in PowerShell
  • Character display garbled or encoding problems

Recommended Solution:

📝 Suggestion: Prioritize Using Git Bash

  1. Install Git for Windows

    # Visit https://git-scm.com/download/win to download and install

  2. Open Git Bash

    • Method 1: Right-click folder → "Git Bash Here"
    • Method 2: Search "Git Bash" in Start Menu

  3. Verify Environment

    # Run in Git Bash, confirm output contains bash
    echo $0

    # Test CLI command
    lovrabet --help

  4. Terminal Support Status

    • ✅ Git Bash - Fully tested and verified, recommended
    • ⚠️ Windows CMD - Basic functions available, not fully tested
    • ⚠️ PowerShell - Basic functions available, may have some limitations
    • ⚠️ Windows Terminal - Depends on specific shell configuration

🙅‍♂️ Node.js Version Too Old​

Symptoms:

  • Error when installing CLI
  • Prompt about unsupported syntax
  • Commands cannot execute properly

Solution:

# 1. Check current Node.js version
node --version

# 2. If version < 20, need to upgrade
# Visit https://nodejs.org/, download latest LTS version

# 3. Reinstall CLI after installation
npm install --global @lovrabet/cli

Windows Users Special Attention:

  • After installing Node.js, close all Git Bash windows and reopen
  • Must verify in Git Bash: node --version
  • If you see Node.js in CMD but not in Git Bash, may need to restart computer

📦 Cannot Download Lovrabet CLI​

Symptoms:

  • npm install --global @lovrabet/cli reports 404 error
  • Prompt package not found
  • Network connection timeout

Solution:

  1. Check npm source configuration

    # View npm configuration
    npm config list

    # Check ~/.npmrc file
    cat ~/.npmrc

  2. Configure private registry

    # Add to ~/.npmrc (contact administrator for correct address)
    @lovrabet:registry=https://your-private-registry.com/

  3. Network issues

    • Check network connection
    • Turn off VPN or proxy
    • Contact IT support for enterprise firewall issues

Login Authentication Issues​

🔐 Login Keeps Failing​

Symptoms:

  • Prompted to re-login every time
  • Browser cannot open local address
  • Still shows unauthorized after login

Solution:

  1. Clear login cache

    # Delete login information file
    rm -rf ~/.lovrabet/

    # Re-login
    lovrabet auth

  2. Browser issues

    • Chrome/Edge: Click "Advanced" → "Proceed to"
    • Firefox: Click "Advanced" → "Add Exception"
    • Safari: Click "Show Details" → "Visit Website"

  3. System security software

    • Temporarily disable firewall or antivirus software
    • Add CLI to trusted list
    • On company network may need to contact IT administrator

🌐 API Pull Failed​

Symptoms:

  • Prompt "Please configure application Code first"
  • Prompt Cookie invalid or expired
  • Network request timeout or failure

Solution:

  1. Check login status

    # Re-login
    lovrabet auth

    # Try again after confirming login success
    lovrabet api pull

  2. Check application configuration

    # View current configuration
    lovrabet config list

    # Set application code
    lovrabet config set app your-app-code

    # Or pass parameter directly
    lovrabet api pull your-app-code

  3. Network issues

    # Check network connection
    ping api.lovrabet.com

    # Retry later
    lovrabet api pull

Development Runtime Issues​

🚀 Development Server Failed to Start​

Symptoms:

  • lovrabet start command errors
  • Vite cannot start
  • Port occupied

Solution:

  1. Check project dependencies

    # Check if vite exists in package.json
    cat package.json | grep vite

    # If not, reinstall dependencies
    npm install
    # or
    yarn install

  2. Port conflict

    # View process occupying port 5173
    lsof -i :5173

    # Kill process occupying port
    kill -9 <process-id>

    # Or specify different port
    PORT=3000 lovrabet start

  3. View detailed logs

    # View CLI logs
    lovrabet logs

    # Or run vite directly
    npx vite

Page Generation Issues​

📄 Page Creation Failed​

Symptoms:

  • Route path format incorrect
  • Prompt directory already exists
  • Template file corrupted or missing

Solution:

  1. Check route format

    # Correct examples
    about
    user/profile
    admin/user/list

    # Wrong examples
    /about        # Cannot start with /
    about/        # Cannot end with /
    user profile  # Cannot contain spaces
    user@profile  # Cannot contain special characters

  2. Handle directory conflict

    # Check if already exists
    ls src/pages/user/profile

    # If exists, use different path
    # Or delete and recreate
    rm -rf src/pages/user/profile
    lovrabet add page

  3. Template issues

    # Check if CLI template files are complete
    # If encountering template errors, may need to reinstall CLI
    npm install --global @lovrabet/cli

General Troubleshooting Steps​

When you encounter any problem, follow these steps in order:

1️⃣ Collect Information​

# View CLI version
lovrabet --version

# View Node.js version
node --version

# View operating system
uname -a  # Linux/Mac
ver       # Windows

2️⃣ View Logs​

# View CLI logs
lovrabet logs

# Clear logs and retry
lovrabet logs --clear

3️⃣ Check Configuration​

# View project configuration
lovrabet config list

# View login status
ls ~/.lovrabet/

4️⃣ Reset Environment​

# Re-login
rm -rf ~/.lovrabet/
lovrabet auth

# Reinstall CLI
npm uninstall --global @lovrabet/cli
npm install --global @lovrabet/cli

Still Can't Resolve?​

If you've tried all the above methods and still can't resolve the issue, you can:

  1. Check official documentation: Confirm your operation steps are correct
  2. Ask colleagues: See if others have encountered the same problem
  3. Contact technical support: Provide detailed error information and logs

When seeking help, please provide:

  • CLI version number
  • Node.js version number
  • Operating system version
  • Specific error message
  • Operation steps
  • CLI log content