Troubleshooting - EnConvo Documentation

Overview

This guide covers the most common issues users encounter with EnConvo and how to resolve them. If your issue is not listed here, reach out on our Discord community.

Node.js Process Issues

EnConvo uses a Node.js process for extension execution. If extensions fail to load or respond, the Node.js service may need attention.

Symptoms

Extensions do not respond
Chat messages hang with no response
“Connection failed” errors
SmartBar opens but commands do not execute

Solutions

Restart the Node.js service

Click the EnConvo menu bar icon
Select “Restart Node.js Service”
Wait 5-10 seconds for the service to reinitialize

This resolves most connection issues.

Check the socket connection

The Unix Domain Socket file should exist at:

~/.config/Enconvo/.macopilot.socket

If this file is missing, restart EnConvo completely (Quit → Relaunch).

Kill orphaned Node.js processes

If the Node.js process is stuck, terminate it manually:

# Find EnConvo-related Node.js processes
ps aux | grep -i enconvo | grep node

# Kill the process (replace PID with the actual process ID)
kill -9 <PID>

Then restart EnConvo.

Check Node.js version

EnConvo requires Node.js 18+. Check your version:

node --version

If you have an older version, update via nodejs.org or:

brew install node

Extension Loading Failures

Symptoms

“Extension not found” error
Extension appears in list but does not work
“Failed to load command” message

Solutions

Reinstall the extension

Settings → Extensions → Find the extension
Uninstall it
Reinstall from the Extension Store

Check extension path

Extensions are installed to:

~/.config/enconvo/extension/{extensionName}/

Verify the extension directory exists and contains a package.json:

ls ~/.config/enconvo/extension/{extensionName}/

Clear extension cache

Remove the extension’s cached build artifacts:

rm -rf ~/.config/enconvo/extension/{extensionName}/node_modules

Then restart EnConvo to trigger a rebuild.

Check for version incompatibility

Some extensions require a minimum EnConvo version. Check the extension’s package.json:

"minAppVersion": "1.8.8"

Update EnConvo if your version is older.

AI Model Issues

No Response from AI

Verify API key

Settings → Key Management
Find your provider (OpenAI, Anthropic, etc.)
Click “Validate” to test the key
If validation fails, re-enter your API key

Check network connection

Cloud AI providers require internet access:

# Test connectivity to OpenAI
curl -s https://api.openai.com/v1/models -H "Authorization: Bearer YOUR_KEY" | head -20

# Test connectivity to Anthropic
curl -s https://api.anthropic.com/v1/messages -H "x-api-key: YOUR_KEY" | head -20

Check proxy settings

If you use a proxy, configure it in Settings → Network → HTTP Proxy. Some corporate networks block AI API endpoints.

Check API quota

You may have exhausted your API quota or hit rate limits. Check your provider’s dashboard:

Try a different model

Switch to a different model or provider temporarily to isolate the issue. If other models work, the problem is specific to the original model or provider.

Slow Responses

Large context: Reduce the amount of context being sent (fewer tools, smaller knowledge base results)
Model selection: Smaller models (e.g., GPT-4o-mini, Claude 3.5 Haiku) respond faster
Local models: Local models on Apple Silicon may be slow with large contexts. Consider using cloud providers for long conversations

Ollama/Local Model Issues

Ollama not connecting

Verify Ollama is running:
```
ollama list
```
Check the server URL in Settings matches Ollama’s address (default: http://localhost:11434)
Restart Ollama:
```
ollama serve
```

Model not found

Pull the model first:

ollama pull llama3.2

Then refresh the model list in EnConvo: Settings → AI Models → Ollama → Refresh

Audio & Microphone Issues

Dictation Not Working

Check microphone permission

System Settings → Privacy & Security → Microphone
Ensure EnConvo is listed and enabled
If not listed, trigger dictation once — macOS will prompt for permission

Check input device

Settings → Voice → Input Device
Select the correct microphone
Test with macOS Sound preferences to verify the mic works

Check dictation provider

Settings → Voice → Dictation Provider
Try the “Microsoft (Enconvo Cloud Plan) Free” provider — it requires no API key
If using a custom provider, verify the API key

TTS (Read Aloud) Not Working

Check TTS provider

Settings → Voice → TTS Provider. Try “macOS System TTS” as a fallback — it requires no API key and works offline.

Check audio output

Verify your Mac’s audio output is not muted and the volume is up. Try playing audio in another app to confirm.

Keyboard Shortcut Issues

Shortcut Does Not Work

Check for conflicts

Another app may have claimed the same shortcut. Common conflicts:

Spotlight (Cmd + Space)
Alfred/Raycast (various shortcuts)
macOS Screenshots (Cmd + Shift + 3/4/5)
Other productivity tools

Change EnConvo’s shortcut in Settings, or disable the conflicting shortcut in the other app.

Grant Accessibility permission

Global shortcuts require Accessibility permission:

System Settings → Privacy & Security → Accessibility
Find EnConvo in the list and enable it
If already enabled, try toggling it off and on
Restart EnConvo

Restart EnConvo

Shortcut registration can sometimes fail. Quit and relaunch EnConvo.

Accessibility Permission Issues

Selected Text Not Detected

EnConvo needs Accessibility permission to read selected text for PopBar and context awareness.

Open System Settings

System Settings → Privacy & Security → Accessibility

Enable EnConvo

Toggle EnConvo on. If it is already on, toggle it off, wait 2 seconds, then toggle it back on.

Restart EnConvo

Quit and relaunch EnConvo for the permission change to take effect.

Verify

Select text in any app and check if PopBar appears or if SmartBar context detection works.

Screen Recording Permission

Screenshot OCR and screen context require Screen Recording permission:

System Settings → Privacy & Security → Screen & System Audio Recording (or Screen Recording)
Enable EnConvo
Restart EnConvo

On macOS Ventura (13) and later, you may need to remove and re-add EnConvo from the Accessibility and Screen Recording lists if permissions are not taking effect after an app update.

Knowledge Base Issues

Documents not being indexed

Check the embedding provider is configured and working (Settings → Knowledge Base → Embedding Model)
Verify the document format is supported (PDF, TXT, MD, DOCX, HTML, etc.)
Check the console logs for indexing errors

Search returns no results

Ensure the knowledge base is selected in the chat context
Try lowering the Score Threshold in Knowledge Base settings
Increase the Top K Results count
Re-index the knowledge base if documents were recently added

Knowledge base is large and slow

Consider splitting into multiple smaller, topic-focused knowledge bases
Enable a Reranker provider to improve result quality without increasing Top K
Use smaller embedding models for faster indexing

Browser Control Issues

Cannot connect to browser

Install the Enconvo Companion extension in your browser
Ensure the browser supports Chrome DevTools Protocol (Chrome, Edge, Brave, Arc, Vivaldi, Opera)
Restart the browser after installing the extension

Firefox support

Firefox requires additional configuration for DevTools Protocol. Chrome-based browsers are recommended for the best experience.

Viewing Logs

Logs are essential for diagnosing issues that are not covered above.

Extension Logs

View logs from individual extensions:

Enable Developer Mode: Settings → Advanced → Developer Mode → On
Open the log viewer in the debug panel
Logs show real-time extension output, errors, and JSON-RPC messages

System Logs

View EnConvo’s system-level logs in macOS Console:

# View recent EnConvo logs
log show --predicate 'subsystem == "com.frostyeve.enconvo"' --last 1h

# Stream live logs
log stream --predicate 'subsystem == "com.frostyeve.enconvo"'

Node.js Server Logs

The Node.js server logs to stdout. When running in development:

# Check if the Node.js server is running
ps aux | grep enconvo | grep node

Submitting a Bug Report

If you cannot resolve an issue, submit a bug report:

Gather information

Collect:

EnConvo version (Settings → About)
macOS version
Steps to reproduce the issue
Error messages (screenshots or text)
Relevant logs

Report on Discord

Join discord.gg/jYsdVRRK2k and post in the #bug-reports channel with:

Description of the issue
Steps to reproduce
Expected vs actual behavior
Your collected information

Report on GitHub

For extension-specific bugs, open an issue on the relevant GitHub repository:

Include the extension name and version
Attach relevant log snippets
Describe your configuration

The more detail you provide in bug reports, the faster the issue can be diagnosed. Screenshots, log snippets, and exact reproduction steps are extremely helpful.

Common Quick Fixes

For reference, here is a summary of the most effective quick fixes:

Issue	Quick Fix
Extensions not responding	Menu Bar → Restart Node.js Service
AI not responding	Settings → Key Management → Validate key
Shortcuts not working	System Settings → Accessibility → Toggle EnConvo
PopBar not appearing	System Settings → Accessibility → Enable EnConvo
OCR not working	System Settings → Screen Recording → Enable EnConvo
Dictation failing	Settings → Voice → Try “Microsoft Free” provider
Ollama not connecting	Run `ollama serve` in Terminal
Extension missing	Reinstall from Extension Store
Everything broken	Quit EnConvo → Relaunch

Next Steps

Settings Reference

Review all configurable settings

Privacy & Security

Understand data handling

Discord Community

Get help from the community

FAQ

Frequently asked questions

Getting Started

Core Features

AI Capabilities

Providers

Workflows & Extensions

Integrations

Advanced

Configuration

Resources

Documentation Index

​Overview

​Node.js Process Issues

​Symptoms

​Solutions

​Extension Loading Failures

​Symptoms

​Solutions

​AI Model Issues

​No Response from AI

​Slow Responses

​Ollama/Local Model Issues

​Audio & Microphone Issues

​Dictation Not Working

​TTS (Read Aloud) Not Working

​Keyboard Shortcut Issues

​Shortcut Does Not Work

​Accessibility Permission Issues

​Selected Text Not Detected

​Screen Recording Permission

​Knowledge Base Issues

​Browser Control Issues

​Viewing Logs

​Extension Logs

​System Logs

​Node.js Server Logs

​Submitting a Bug Report

​Common Quick Fixes

​Next Steps

Settings Reference

Privacy & Security

Discord Community

FAQ

Overview

Node.js Process Issues

Symptoms

Solutions

Extension Loading Failures

Symptoms

Solutions

AI Model Issues

No Response from AI

Slow Responses

Ollama/Local Model Issues

Audio & Microphone Issues

Dictation Not Working

TTS (Read Aloud) Not Working

Keyboard Shortcut Issues

Shortcut Does Not Work

Accessibility Permission Issues

Selected Text Not Detected

Screen Recording Permission

Knowledge Base Issues

Browser Control Issues

Viewing Logs

Extension Logs

System Logs

Node.js Server Logs

Submitting a Bug Report

Common Quick Fixes

Next Steps