Troubleshooting

This page covers common issues you might encounter when using Livedocs Anywhere and how to resolve them.

Installation Issues

”command not found: livedocs”

Your shell doesn’t know where to find the livedocs binary. This usually means ~/.livedocs/bin isn’t in your PATH.

Solutions:

Open a new terminal — If you just installed, your current terminal won’t have the updated PATH.

Source your shell config:

source ~/.zshrc    # for zsh
source ~/.bashrc   # for bash

Re-run the installer with PATH setup:

curl -fsSL https://livedocs.com/install.sh | bash -s -- --setup-path

Add to PATH manually — Add this line to your shell config (~/.zshrc, ~/.bashrc, etc.):
```
export PATH="$HOME/.livedocs/bin:$PATH"
```

“uv is required”

The CLI needs uv to manage Python environments.

Solution:

Install uv first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then re-run the Livedocs installer.

”python3 is required to parse the manifest”

The installer uses Python to read the bundle manifest during installation.

Solution:

Install Python 3:

# macOS
brew install python3

# Ubuntu/Debian
sudo apt-get install python3

# Fedora
sudo dnf install python3

Authentication Issues

”Workspace token not found”

The CLI doesn’t have a valid authentication token.

Solution:

Run the setup command to authenticate:

livedocs setup

If you’ve already set up but still see this error, your token may have expired or been revoked. Run setup again to get a new token.

”Invalid workspace token” or 401 errors

Your stored token is no longer valid.

Solution:

Clear your existing credentials and re-authenticate:

livedocs logout
livedocs setup

Setup hangs or times out

The device code flow is waiting for you to approve in the browser.

Solutions:

Check if a browser window opened — look for a Livedocs tab
If not, look at the terminal output for a URL to visit manually
Use --no-browser to get the URL without auto-opening:
```
livedocs setup --no-browser
```
For headless servers, use an API token instead:
```
livedocs setup --api-token YOUR_TOKEN
```

Session Issues

Session fails to start

Check the logs for details:

livedocs logs --session SESSION_ID

Common causes:

Port conflict — Another process is using the required port.

# Check what's using port 8000
lsof -i :8000

Corrupted environment — Reinstall the bundle:

livedocs update --force

Stale session — Clean up old sessions:

livedocs gc --all

“No bundle currently active”

The CLI can’t find an installed bundle.

Solution:

Run the installer or update command:

livedocs update

Browser doesn’t open

The CLI tried to open your browser but couldn’t.

Solutions:

Copy the URL from the terminal output and paste it in your browser

Check the open command works on your system:

open https://livedocs.com  # macOS
xdg-open https://livedocs.com  # Linux

Session runs but notebook won’t connect

The runtime started but the browser can’t reach it.

Possible causes:

Firewall blocking localhost — Check your firewall settings allow connections to localhost
VPN interference — Some VPNs intercept localhost traffic. Try disconnecting
Browser security — Some browsers block mixed content (HTTPS page connecting to HTTP localhost). This is expected and should work with Livedocs

Check session status:

livedocs status --verbose

Performance Issues

Slow startup

First launch is slower because it bootstraps the Python environment. Subsequent launches reuse the cached environment.

If startup remains slow:

Check available disk space in ~/.livedocs
Try cleaning up old sessions:
```
livedocs gc
```
Check system resources (CPU, memory, disk I/O)

High memory usage

Each session runs Middleman and Jedi processes. Memory usage depends on:

Your notebook’s data size
Number of active dataframes
AI features enabled

To reduce memory:

Stop sessions you’re not using: livedocs stop --all
Clean up old sessions: livedocs gc

Getting Help

Collecting diagnostics

When reporting issues, gather this information:

# CLI version and status
livedocs --version
livedocs status --verbose

# Recent logs
livedocs logs

# System info
uname -a
python3 --version
uv --version

Log locations

Logs are stored in ~/.livedocs/logs/ organized by session ID:

~/.livedocs/logs/
  SESSION_ID/
    middleman.log
    jedi.log

Contacting support

Email support@livedocs.com with:

Description of the issue
Steps to reproduce
Output from the diagnostic commands above
Relevant log snippets