Skip to main content

Troubleshooting

Encountering problems? Don't worry! Here we've collected the most common issues and solutions. Most problems can find answers 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 basic compatibility
    • macOS/Linux: Any terminal works
  2. Check Node.js version: node --version (requires >= 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 encoding or display issues

Recommended Solution:

📝 Suggestion: Use Git Bash First

  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 thoroughly tested
    • ⚠️ PowerShell - Basic functions available, may have some limitations
    • ⚠️ Windows Terminal - Depends on the specific shell type configured

Node.js Version Too Old​

Error Symptoms:

  • Error when installing CLI
  • Syntax not supported
  • 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. Re-install CLI after installation completes
npm install --global @lovrabet/cli

Windows Users Special Note:

  • 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, you may need to restart your computer

Cannot Download Lovrabet CLI​

Error Symptoms:

  • npm install --global @lovrabet/cli shows 404 error
  • 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 admin for correct address)
    @lovrabet:registry=https://your-private-registry.com/

  3. Network issues

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

Login Authentication Issues​

Login Always Fails​

Error Symptoms:

  • Always prompted to re-login
  • Browser cannot open local address
  • Still shows unauthorized after login

Solution:

  1. Clear login cache

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

    # Re-login
    lovrabet auth

  2. Browser issues

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

  3. System security software

    • Temporarily disable firewall or antivirus
    • Add CLI to trusted list
    • May need to contact IT admin on corporate network

API Pull Failed​

Error Symptoms:

  • Prompt "Please configure app code first"
  • 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 as 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 Fails to Start​

Error Symptoms:

  • lovrabet start command errors
  • Vite cannot start
  • Port is 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 the process occupying the port
    kill -9 <process-id>

    # Or specify another 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​

Error Symptoms:

  • Route path format incorrect
  • 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 conflicts

    # 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, you can troubleshoot in the following 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 try again
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 Solve It?​

If you've tried all the above methods and still can't solve it, you can:

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

Please provide the following information when seeking help:

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