# Troubleshooting Guide
Common issues and solutions for the RemNote MCP Server.
## Quick Diagnostics
Before diving into specific issues, verify the basic setup:
```bash
# 1. Check server is running
ps aux | grep remnote-mcp-server
# 2. Check ports are listening
lsof -i :3001 # HTTP MCP port
lsof -i :3002 # WebSocket port
# 3. Check server logs
# (if using --log-file, check that file)
# 4. Check MCP client configuration
cat ~/.claude.json | grep -A 5 remnote
# 5. Check RemNote plugin status
# (Open RemNote → Plugin control panel)
# 6. Check server version
remnote-mcp-server --version
```
## Server Issues
### Server Not Starting
**Symptom:** Server command doesn't start or exits immediately
**Possible causes:**
1. **Command not found**
```bash
remnote-mcp-server: command not found
```
**Solution:**
```bash
# Verify installation
which remnote-mcp-server
# If not found, reinstall
npm install -g remnote-mcp-server
# Or check npm bin directory is in PATH
echo $PATH
npm config get prefix
```
2. **Node.js version too old**
```bash
# Check version
node --version
# Requires >= 18.0.0
# Update Node.js
nvm install 18
nvm use 18
```
3. **Missing dependencies**
```bash
# For development installs
cd /path/to/remnote-mcp-server
npm install
npm run build
npm link
```
### Port Already in Use
**Symptom:** `EADDRINUSE: address already in use` error
**Solution:**
```bash
# Find what's using the ports
lsof -i :3001
lsof -i :3002
# Kill the process if needed
kill -9 <PID>
# Or use different ports
remnote-mcp-server --http-port 3003 --ws-port 3004
```
**For custom ports:**
1. Update MCP client configuration to use new HTTP port
2. Update RemNote plugin settings to use new WebSocket port
### Permission Errors
**Symptom:** `EACCES: permission denied` when starting server
**Solution:**
```bash
# Use ports above 1024 (don't require root)
remnote-mcp-server --http-port 3001 # Default, should work
# If you need ports below 1024, use sudo (not recommended)
sudo remnote-mcp-server --http-port 80
```
**For global installation permission errors:**
```bash
# Use nvm (recommended)
# See https://github.com/nvm-sh/nvm
# Or fix npm permissions
# See https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally
```
### Server Starts But No Output
**Symptom:** Server starts but shows no log output
**Expected behavior:** Modern versions use structured logging. On first start, you should see:
```
RemNote MCP Server v0.2.1 listening { wsPort: 3002, httpPort: 3001 }
```
**If you see nothing:**
1. Check the server actually started:
```bash
lsof -i :3001
```
2. Check for verbose output:
```bash
remnote-mcp-server --verbose
```
3. Log to file to capture output:
```bash
remnote-mcp-server --log-file /tmp/remnote-mcp.log --verbose
tail -f /tmp/remnote-mcp.log
```
## RemNote Plugin Issues
### Plugin Won't Connect
**Symptom:** Server running but plugin shows "Disconnected" status
**Solutions:**
1. **Verify plugin settings in RemNote:**
- WebSocket URL: `ws://127.0.0.1:3002`
- Auto-reconnect: Enabled
- Check for typos in URL
2. **Verify WebSocket port is listening:**
```bash
lsof -i :3002
# Should show node process
```
3. **Check server logs for connection attempts:**
```bash
remnote-mcp-server --verbose
# Look for WebSocket connection messages
```
4. **Restart RemNote** after changing plugin settings
5. **Reinstall plugin** if persistent:
- Remove plugin from RemNote
- Restart RemNote
- Reinstall plugin from [GitHub](https://github.com/robert7/remnote-mcp-bridge)
6. **Check plugin console for errors:**
- Open RemNote Developer Tools: `Cmd+Option+I` (macOS) or `Ctrl+Shift+I` (Windows/Linux)
- Look for error messages in Console tab
### Plugin Connects Then Disconnects
**Symptom:** Plugin shows "Connected" briefly, then "Disconnected"
**Possible causes:**
1. **Server crashed** - Check server is still running:
```bash
ps aux | grep remnote-mcp-server
```
2. **Port conflict** - Another process took the port:
```bash
lsof -i :3002
```
3. **Network issue** - Check firewall settings (unlikely for localhost)
**Solution:**
- Restart server with verbose logging:
```bash
remnote-mcp-server --verbose --log-file /tmp/remnote-debug.log
```
- Check logs for error messages
- Enable plugin auto-reconnect
### Bridge / Server Version Mismatch After Upgrade
**Symptom:** Plugin shows `Connected`, but MCP tool calls fail after upgrading the bridge plugin or server
**Solution:**
1. Check plugin version in the Automation Bridge panel (or via `remnote_status` output `pluginVersion`).
2. Check server version: `remnote-mcp-server --version`.
3. Install a compatible server version for the bridge plugin version (`0.x` minor versions may break compatibility).
4. See the [Bridge / Consumer Version Compatibility
Guide](https://github.com/robert7/remnote-mcp-bridge/blob/main/docs/guides/bridge-consumer-version-compatibility.md).
### Plugin Shows Wrong Version
**Symptom:** `remnote_status` shows old plugin version
**Solution:**
1. Update RemNote Automation Bridge plugin:
- Visit [GitHub repository](https://github.com/robert7/remnote-mcp-bridge)
- Follow update instructions
2. Hard refresh RemNote (clear cache):
- Close RemNote completely
- Clear cache (method depends on platform)
- Restart RemNote
## MCP Client Issues
### Tools Not Appearing in Claude Code
**Symptom:** RemNote tools don't show up in Claude Code CLI
**Solutions:**
1. **Verify server is running:**
```bash
lsof -i :3001
```
2. **Check configuration in `~/.claude.json`:**
```bash
cat ~/.claude.json | grep -A 10 mcpServers
```
3. **Verify configuration format is correct:**
✅ **Correct:**
```json
{
"projects": {
"/Users/username": {
"mcpServers": {
"remnote": {
"type": "http",
"url": "http://localhost:3001/mcp"
}
}
}
}
}
```
❌ **Incorrect (old stdio format):**
```json
{
"type": "stdio",
"command": "remnote-mcp-server"
}
```
4. **Restart Claude Code CLI completely** (not just reload)
5. **Check MCP client logs:**
```bash
tail -f ~/.claude/debug/mcp-*.log
```
6. **Test connection using CLI:**
```bash
claude mcp list
# Should show: remnote: http://localhost:3001/mcp (HTTP) - ✓ Connected
```
### Connection Timeout
**Symptom:** MCP client shows connection timeout
**Solutions:**
1. **Verify server is running and responding** (see [Testing the MCP HTTP Endpoint](#testing-the-mcp-http-endpoint))
2. **Check for firewall blocking localhost** (rare but possible)
3. **Verify port number matches configuration:**
```bash
# Check server port
lsof -i :3001
# Check configuration
cat ~/.claude.json | grep -A 5 remnote
```
4. **Try different port:**
```bash
remnote-mcp-server --http-port 3003
# Update configuration to match
```
### `Invalid session ID` After Server Restart
**Symptom:** Claude Code tool calls fail after restarting `remnote-mcp-server` with an error like:
```text
Invalid session ID: ...
```
**Cause:** MCP HTTP sessions are stored in memory. Restarting the server invalidates existing sessions. Some MCP clients
(including current Claude Code versions) may continue using the old session ID instead of reinitializing.
**What to do:**
1. **Restart Claude Code CLI completely** (or otherwise refresh the MCP connection/session)
2. **Retry the tool call**
3. **Check Claude Code MCP logs** if it still fails:
```bash
tail -f ~/.claude/debug/mcp-*.log
```
**Notes:**
- The server now returns a clearer error indicating reinitialization is required after invalid/expired sessions
- This is expected after server restarts until the client performs a new MCP handshake (`initialize` +
`notifications/initialized`)
### Configuration Not Working
**Symptom:** Configuration changes don't take effect
**Solutions:**
1. **Ensure configuration is in correct location:**
- Modern: `~/.claude.json` with `mcpServers` key
- Old (deprecated): `~/.claude/.mcp.json`
2. **Verify JSON syntax:**
```bash
cat ~/.claude.json | jq .
# Should parse without errors
```
3. **Check project path matches:**
- Configuration must be under correct project path in `~/.claude.json`
- Use home directory path for global configuration
4. **Restart Claude Code CLI completely:**
- Quit Claude Code CLI
- Wait a few seconds
- Restart
5. **Use CLI to manage configuration:**
```bash
# Remove old configuration
claude mcp remove remnote
# Re-add with CLI
claude mcp add remnote --transport http http://localhost:3001/mcp
```
## Tool Execution Issues
### Tools Return Errors
**Symptom:** MCP tools execute but return error messages
**Common errors:**
1. **"Note not found"**
- Verify Rem ID is correct
- Use `remnote_search` to find correct ID
- Check note hasn't been deleted
2. **"Invalid parameter"**
- Check parameter types match requirements
- See [Tools Reference](tools-reference.md) for correct usage
3. **"RemNote plugin not connected"**
- Check plugin status in RemNote
- Verify WebSocket connection
- See [Plugin Won't Connect](#plugin-wont-connect)
4. **"Request timeout"**
- Check RemNote app is responsive
- Check server logs for errors
- Increase timeout if needed (not configurable yet - file an issue)
### Search Returns No Results
**Symptom:** `remnote_search` returns empty results even though notes exist
**Solutions:**
1. **Try broader search terms:**
```
Search for "machine" instead of "machine learning algorithms"
```
2. **Check RemNote search works:**
- Manually search in RemNote app
- Verify notes actually contain the search term
3. **Verify plugin connection:**
```
Use remnote_status to check connection
```
4. **Check RemNote indexing:**
- RemNote may need time to index new notes
- Wait a few seconds after creating notes
### Create Note Fails
**Symptom:** `remnote_create_note` returns error or note doesn't appear
**Solutions:**
1. **Check parameters are correct:**
- Title is required
- Content, parentId, tags are optional
- See [Tools Reference](tools-reference.md)
2. **Verify RemNote is responsive:**
- Check RemNote app isn't frozen
- Try creating note manually in RemNote
3. **Check for special characters:**
- Some characters may cause issues
- Try simple title first
4. **Check server logs:**
```bash
remnote-mcp-server --verbose
```
## Network Issues
### Can't Connect from Remote Client
**Symptom:** Claude Cowork or remote client can't connect
**Solutions:**
1. **Verify you've set up remote access:**
- See [Remote Access Guide](remote-access.md)
- Server must be exposed via ngrok or similar
2. **Check tunnel is running:**
```bash
# For ngrok
curl http://127.0.0.1:4040/api/tunnels | jq
```
3. **Verify HTTPS URL (not HTTP):**
- Claude Cowork requires HTTPS
- ngrok provides HTTPS by default
4. **Test tunnel endpoint** (see [Testing the MCP HTTP Endpoint](#testing-the-mcp-http-endpoint) and replace URL with
your ngrok URL)
### Firewall Blocking Connections
**Symptom:** Can't connect even though server is running
**Solutions:**
1. **For localhost connections (should always work):**
- Verify using `localhost` or `127.0.0.1` (not `0.0.0.0`)
- Check no VPN or security software blocking localhost
2. **For network connections:**
- Check firewall rules allow traffic on ports 3001 and 3002
- On macOS: System Preferences → Security & Privacy → Firewall
- On Linux: `sudo ufw status`
3. **For remote connections:**
- Use tunnel service (ngrok) instead of exposing directly
- Firewall shouldn't block outbound tunnel connections
## Performance Issues
### Slow Response Times
**Symptom:** Tools take a long time to respond
**Possible causes:**
1. **Large note hierarchies:**
- Reading deep hierarchies is slower
- Use smaller `depth` parameter in `remnote_read_note`
2. **Many search results:**
- Reduce `limit` parameter in `remnote_search`
- Use `includeContent: false` for faster searches
3. **RemNote app performance:**
- Check RemNote app isn't slow
- Close other heavy applications
- Restart RemNote
4. **Network latency (remote access):**
- ngrok adds latency
- Test locally first to isolate issue
### High CPU Usage
**Symptom:** Server uses excessive CPU
**Solutions:**
1. **Check for request loops:**
- Verify MCP client isn't making rapid repeated requests
- Check server logs for unusual activity
2. **Update to latest version:**
```bash
npm update -g remnote-mcp-server
```
3. **Report issue:**
- File bug report with logs on [GitHub](https://github.com/robert7/remnote-mcp-server/issues)
## Debugging
### Enable Verbose Logging
```bash
remnote-mcp-server --verbose --log-file /tmp/remnote-debug.log
```
### Log WebSocket Communication
```bash
remnote-mcp-server \
--verbose \
--request-log /tmp/requests.jsonl \
--response-log /tmp/responses.jsonl
```
**View logs:**
```bash
# Main log
tail -f /tmp/remnote-debug.log
# Requests
tail -f /tmp/requests.jsonl | jq
# Responses
tail -f /tmp/responses.jsonl | jq
```
### Test Server Manually
#### Testing the MCP HTTP Endpoint
The MCP HTTP server uses Server-Sent Events (SSE) for streaming responses, which requires specific Accept headers.
**Basic connection test:**
```bash
curl -X POST http://localhost:3001/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json, text/event-stream" \
-d '{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "test-client",
"version": "1.0.0"
}
}
}'
```
**Expected response:**
- JSON response with server capabilities
- `mcp-session-id` header in the response
**Common errors:**
- Missing Accept header: `"Not Acceptable: Client must accept both application/json and text/event-stream"`
- Server not running: `curl: (7) Failed to connect to localhost port 3001`
- Wrong port: `curl: (7) Failed to connect`
**For remote/ngrok testing:**
Replace `http://localhost:3001` with your ngrok URL (e.g., `https://abc123.ngrok-free.app`).
See also: [Remote Access Guide](remote-access.md) for ngrok setup.
### Check MCP Client Logs
**Claude Code CLI:**
```bash
tail -f ~/.claude/debug/mcp-*.log
```
### Check RemNote Plugin Console
1. Open RemNote Developer Tools:
- macOS: `Cmd+Option+I`
- Windows/Linux: `Ctrl+Shift+I`
2. Check Console tab for errors
3. Check Network tab for WebSocket traffic
## Getting Help
### Before Filing an Issue
1. Check this troubleshooting guide
2. Search [existing issues](https://github.com/robert7/remnote-mcp-server/issues)
3. Collect diagnostic information:
```bash
# Server version
remnote-mcp-server --version
# Node version
node --version
# OS version
uname -a # or: sw_vers (macOS)
# Check ports
lsof -i :3001
lsof -i :3002
# Capture logs
remnote-mcp-server --verbose --log-file /tmp/debug.log
```
### Filing an Issue
Include in your bug report:
- Server version
- Node.js version
- Operating system
- MCP client (Claude Code, Accomplish, etc.)
- RemNote plugin version
- Steps to reproduce
- Error messages
- Relevant logs (redact sensitive information)
**File issues:** [github.com/robert7/remnote-mcp-server/issues](https://github.com/robert7/remnote-mcp-server/issues)
## Related Documentation
- [Installation Guide](installation.md) - Installation instructions
- [Configuration Guide](configuration.md) - Configuration details
- [CLI Options Reference](cli-options.md) - Command-line options
- [Tools Reference](tools-reference.md) - Tool usage details
- [Remote Access Guide](remote-access.md) - Remote access setup
## Common Solutions Summary
| Issue | Quick Fix |
|-------|-----------|
| Port already in use | `kill $(lsof -t -i:3001); kill $(lsof -t -i:3002)` |
| Plugin won't connect | Check URL: `ws://127.0.0.1:3002` |
| Tools not appearing | `claude mcp list` then restart Claude Code |
| `Invalid session ID` after restart | Restart Claude Code (refresh MCP session), then retry |
| Configuration ignored | Verify `~/.claude.json` format, restart client |
| Connection timeout | Verify server running: `lsof -i :3001` |
| Remote access failing | Use HTTPS ngrok URL with `/mcp` path |
| Slow responses | Reduce `depth`/`limit` parameters |
