Troubleshooting

Common issues and solutions for the Lovelace Neovim extension.

Installation Issues
Connection Problems
Authentication Errors
Task Submission Failures
Task Execution Issues
Agent Worker Problems
Session and Workspace Issues
Performance and Responsiveness
Plugin Loading Issues

Installation Issues

Plugin Not Loaded

Symptom: Commands like :LovelaceHealth are not recognized

Solutions:

Verify plugin installation:
vim
```
:Lazy
" Search for 'lovelace.nvim'
" Should show installed and loaded
```
Check plugin manager configuration:
lua
```
-- For lazy.nvim
{
  "lovelace-ai/lovelace.nvim",
  event = "VeryLazy",
  config = function()
    require("lovelace").setup()
  end
}
```
Force reload:
vim
```
:Lazy reload lovelace.nvim
```
Check for errors:
vim
```
:messages
" Look for Lua errors
```

Dependency Missing

Symptom: Error about missing plenary.nvim or nui.nvim

Solution:

lua

-- Add dependencies to plugin spec
{
  "lovelace-ai/lovelace.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim",
    "MunifTanjim/nui.nvim",
  }
}

Installation Script Fails

Symptom: ./install.sh errors during installation

Solutions:

Check shell permissions:
bash
```
chmod +x ~/.local/share/nvim/lazy/lovelace.nvim/install.sh
./install.sh
```
Check localhost-ctl availability:
bash
```
which localhost-ctl
# Should return path to binary
```
Manual installation:
bash
```
# Follow installation guide manually
# See: /editor-extensions/neovim/installation
```

Connection Problems

"Socket not found" Error

Symptom: :LovelaceHealth shows "Socket not found"

Solutions:

Verify daemon is running:
bash
```
localhost-ctl status
```
Check socket path:
bash
```
localhost-ctl config | grep socket
```
Configure correct socket path:
lua
```
require("lovelace").setup({
  daemon = {
    socket_path = "/actual/path/to/socket.sock"
  }
})
```
Verify socket permissions:
bash
```
ls -la /tmp/lovelace-localhost.sock
# Should be readable by your user
```

"Connection refused" Error

Symptom: Socket exists but connection fails

Solutions:

Start the daemon:
bash
```
localhost-ctl start
```
Check daemon process:
bash
```
ps aux | grep localhost-daemon
```
Check daemon logs:
bash
```
localhost-ctl logs
```
Restart daemon:
bash
```
localhost-ctl restart
```

Health Check Hangs

Symptom: :LovelaceHealth freezes at "Checking connection..."

Solutions:

Cancel health check:
vim
```
<C-c>  " Cancel operation
```
Check daemon responsiveness:
bash
```
timeout 5 localhost-ctl ping
```
Reduce timeout in config:
lua
```
require("lovelace").setup({
  daemon = {
    connection_timeout = 3000,  -- 3 seconds
    retry_count = 1
  }
})
```
Restart both daemon and Neovim:
bash
```
localhost-ctl restart
# Then restart Neovim
```

Authentication Errors

Device Code Expired

Symptom: "Device code expired" during authorization

Solution:

vim

" Restart authorization flow
:LovelaceAuth

" Complete within 10 minutes this time

Browser Doesn't Open

Symptom: Pressing o in device flow doesn't open browser

Solutions:

Manual navigation:
- Copy URL from device flow window
- Open browser manually
- Navigate to URL
Check default browser:
bash
```
# macOS
open https://uselovelace.com/device

# Linux
xdg-open https://uselovelace.com/device
```
Set BROWSER environment variable:
bash
```
export BROWSER=firefox
# Or chrome, safari, etc.
```

Code Copy Fails

Symptom: Pressing c doesn't copy device code

Solutions:

Check clipboard support:
vim
```
:echo has('clipboard')
" Should return 1
```
Install clipboard provider (Linux):
bash
```
sudo apt install xclip  # or xsel
```
Manual copy:
- Select code with mouse
- Copy with Cmd+C / Ctrl+C

"Authentication failed" After Device Flow

Symptom: Device flow completes but authentication still fails

Solutions:

Verify account status:
- Visit https://uselovelace.com/settings
- Check account is active
Check daemon auth:
bash
```
localhost-ctl auth status
```
Clear credentials and retry:
bash
```
localhost-ctl auth logout
```
vim
```
:LovelaceAuth
```

"Session expired" Error

Symptom: Commands fail with "Session expired"

Solution:

vim

:LovelaceAuth
" Complete device authorization again

Task Submission Failures

"Task submission failed" Error

Symptom: :LovelaceTask immediately shows error

Solutions:

Check authentication:
vim
```
:LovelaceAuth
```
Verify daemon connection:
vim
```
:LovelaceHealth
```
Check error details:
vim
```
:messages
" Look for specific error
```
Verify workspace:
vim
```
:LovelaceSession
" Ensure workspace is set
```

"Context collection failed" Error

Symptom: Error about buffer content or selection

Solutions:

Save the file first:
vim
```
:w
```
Check file permissions:
bash
```
ls -la current-file.js
```
Try without selection (normal mode):
vim
```
:LovelaceTask
```

Task Stuck in "Queued" State

Symptom: Task remains queued for extended period

Solutions:

Check agent availability:
vim
```
:LovelaceAgents
" Look for idle workers
```
Verify agents are working:
vim
```
:LovelaceAgents
" Check if busy agents show activity
```
Check daemon logs:
bash
```
localhost-ctl logs | grep task
```
Cancel and resubmit:
vim
```
:LovelaceCancel task_abc123
:LovelaceTask
```

Task Execution Issues

Task Takes Too Long

Symptom: Task running for > 10 minutes with no progress

Solutions:

Check task progress:
vim
```
:LovelaceTaskStatus task_abc123
" See if progress updates are appearing
```
Cancel if stuck:
vim
```
:LovelaceCancel task_abc123
```
Resubmit with more specific description:
vim
```
:LovelaceTask
" Be more specific about scope and requirements
```

Task Fails with Validation Error

Symptom: Task shows "Failed: Validation error"

Solutions:

Read error details:
vim
```
:LovelaceTaskStatus task_abc123
" Review error message
```
Common causes:
- Task description too vague
- Selected code has syntax errors
- File not saved before submission
Fix and resubmit:
vim
```
" Save file
:w

" Resubmit with clearer description
:LovelaceTask
```

No Result Buffer Opens

Symptom: Task completes but no result window appears

Solutions:

Check UI configuration:
lua
```
require("lovelace").setup({
  ui = {
    result_window = "split"  -- Valid: split, vsplit, tab
  }
})
```
Manually view results:
vim
```
:LovelaceTaskStatus task_abc123
```
Check for window conflicts:
- Close extra windows
- Try again

Agent Worker Problems

No Agents Available

Symptom: :LovelaceAgents shows empty list or all stopped

Solutions:

Check daemon status:
bash
```
localhost-ctl status
```
Restart daemon (spawns fresh agents):
bash
```
localhost-ctl restart
```
Check daemon logs:
bash
```
localhost-ctl logs | grep agent
```

All Agents Busy

Symptom: All agents show "busy" for extended period

Solutions:

Check task status:
vim
```
:LovelaceTasks
" Verify tasks are progressing
```
Cancel hung tasks:
vim
```
:LovelaceCancel task_abc123
```
Wait for completion:
- Complex tasks take time
- Monitor with :LovelaceTasks

Agent Memory Leaks

Symptom: Agent memory grows continuously

Example:

Check 1 (10:00): 250 MB
Check 2 (10:15): 450 MB
Check 3 (10:30): 680 MB

Action: Report to daemon administrator with agent UUID

Session and Workspace Issues

"Session not found" Error

Symptom: :LovelaceSession shows "Session not found"

Solutions:

Create session:
vim
```
:LovelaceHealth
" Triggers session creation

:LovelaceSession
```
Re-authenticate:
vim
```
:LovelaceAuth
```
Check daemon connection:
vim
```
:LovelaceHealth
```

Wrong Workspace Associated

Symptom: Session shows incorrect workspace

Solutions:

Navigate to correct directory:
vim
```
:cd /path/to/correct/project
:LovelaceSession
```
Check git repository:
bash
```
cd /path/to/project
git rev-parse --show-toplevel
```
Restart Neovim in correct location:
bash
```
cd /path/to/correct/project
nvim
```

No Workspace Associated

Symptom: "No workspace associated" warning

Solutions:

Navigate to project directory:
vim
```
:cd ~/Projects/my-project
:LovelaceSession
```
Initialize git repository:
bash
```
cd /path/to/project
git init
```

Performance and Responsiveness

Slow Command Execution

Symptom: Commands take > 5 seconds to respond

Solutions:

Check daemon load:
bash
```
localhost-ctl status
```
Reduce log level:
lua
```
require("lovelace").setup({
  log_level = "warn"  -- Less verbose
})
```
Check system resources:
bash
```
top
# Look for high CPU/memory usage
```

UI Freezes

Symptom: Neovim freezes when running Lovelace commands

Solutions:

Reduce timeout:
lua
```
require("lovelace").setup({
  daemon = {
    connection_timeout = 2000  -- 2 seconds
  }
})
```
Check for blocking operations:
vim
```
:messages
" Look for warnings
```
Disable auto-refresh:
lua
```
require("lovelace").setup({
  ui = {
    auto_refresh = false
  }
})
```

Plugin Loading Issues

Commands Not Available

Symptom: :LovelaceHealth shows "Not an editor command"

Solutions:

Check plugin loaded:
vim
```
:lua print(vim.inspect(package.loaded["lovelace"]))
" Should show table with functions
```
Verify lazy loading config:
lua
```
{
  "lovelace-ai/lovelace.nvim",
  cmd = {
    "LovelaceHealth",
    "LovelaceAuth",
    "LovelaceTask",
    "LovelaceTasks",
    "LovelaceAgents",
    "LovelaceTaskStatus",
    "LovelaceCancel",
    "LovelaceSession",
  }
}
```
Force load manually:
vim
```
:lua require("lovelace")
```

Lua Errors on Startup

Symptom: Error messages when starting Neovim

Solutions:

Check error details:
vim
```
:messages
```
Common issues:
- Missing dependencies
- Incompatible Neovim version
- Conflicting plugins
Verify Neovim version:
vim
```
:version
" Requires Neovim 0.9.0+
```

Diagnostic Commands

When troubleshooting, gather information with these commands:

Extension Diagnostics

vim

:LovelaceHealth          " Connection and auth status
:LovelaceSession         " Session and workspace info
:LovelaceAgents          " Agent worker status
:LovelaceTasks           " Task queue and history
:messages                " Vim error messages

System Diagnostics

bash

localhost-ctl status     # Daemon status
localhost-ctl logs       # Daemon logs
localhost-ctl config     # Configuration
localhost-ctl ping       # Connection test

Neovim Diagnostics

vim

:checkhealth lovelace    " Plugin health check
:Lazy                    " Plugin manager status
:lua print(vim.inspect(require("lovelace").config))  # Config

Getting Help

If you've tried the solutions above and still have issues:

Check daemon logs:
bash
```
localhost-ctl logs --tail 100 > lovelace-logs.txt
```
Gather diagnostic info:
vim
```
:LovelaceHealth
:LovelaceSession
" Save output
```
Check version information:
vim
```
:version
" Note Neovim version
```
bash
```
localhost-ctl --version
# Note daemon version
```
Report issue with:
- Steps to reproduce
- Error messages
- Diagnostic output
- Version information

Common Error Messages Reference

Error Message	Most Likely Cause	Quick Fix
"Socket not found"	Daemon not running	`localhost-ctl start`
"Connection refused"	Daemon stopped	`localhost-ctl restart`
"Authentication failed"	Session expired	`:LovelaceAuth`
"Task submission failed"	Not authenticated	`:LovelaceAuth`
"No agents available"	Daemon not running	`localhost-ctl restart`
"Session not found"	Never authenticated	`:LovelaceAuth`
"Task not found"	Invalid task ID	Check `:LovelaceTasks`
"Workspace not found"	Not in project directory	`:cd /path/to/project`

Troubleshooting

Table of Contents

Installation Issues

Plugin Not Loaded

Dependency Missing

Installation Script Fails

Connection Problems

"Socket not found" Error

"Connection refused" Error

Health Check Hangs

Authentication Errors

Device Code Expired

Browser Doesn't Open

Code Copy Fails

"Authentication failed" After Device Flow

"Session expired" Error

Task Submission Failures

"Task submission failed" Error

"Context collection failed" Error

Task Stuck in "Queued" State

Task Execution Issues

Task Takes Too Long

Task Fails with Validation Error

No Result Buffer Opens

Agent Worker Problems

No Agents Available

All Agents Busy

Agent Memory Leaks

Session and Workspace Issues

"Session not found" Error

Wrong Workspace Associated

No Workspace Associated

Performance and Responsiveness

Slow Command Execution

UI Freezes

Plugin Loading Issues

Commands Not Available

Lua Errors on Startup

Diagnostic Commands

Extension Diagnostics

System Diagnostics

Neovim Diagnostics

Getting Help

Common Error Messages Reference

Related Documentation