# Troubleshooting

> Diagnose and help resolve common issues with content processing, channel connectivity, browser control, and audio features.

- Skill: `eclaire-labs/troubleshooting` (Agent Skill)
- Install (CLI): `npx skillmds@latest add eclaire-labs/troubleshooting`
- Raw SKILL.md: https://api.skillmd.com/api/skills/eclaire-labs/troubleshooting/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: eclaire-labs (https://skillmd.com/u/eclaire-labs)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/eclaire-labs/troubleshooting

---


# Troubleshooting Guide

## Content Processing Pipeline

When content is added to Eclaire, it goes through a processing pipeline:

1. **Queued** (pending) — Item is saved and waiting for a worker to pick it up
2. **Processing** — A worker is actively working on it (extracting text, generating thumbnails, etc.)
3. **Completed** — Processing finished successfully
4. **Failed** — Processing encountered an error
5. **Retry Pending** — A failed job is queued for automatic retry

You can check the processing status of any item or get an overall summary of the processing pipeline.

### Common Processing Problems

**Content not appearing or stuck**:
- Check the processing status for the specific item to see what stage it's at
- A large backlog of pending items may indicate workers are busy — get the overall summary to see counts
- The user can trigger reprocessing from the item's detail page in the web UI

**Content failed to process**:
- Check the specific item's processing status to see the error message
- Common failures include: network errors when fetching bookmark URLs, unsupported document formats, or corrupted image files
- Suggest trying to reprocess the item from the detail page

**Bookmark not loading content**:
- The target website may be unreachable, behind authentication, or blocking automated access
- Check the processing status for specific error details
- Basic metadata (title, description) may still be available even if full content extraction failed

**Document text not searchable**:
- The document may be a scanned/image-based PDF without text extraction
- Processing may still be in progress — check the status
- Some file formats have limited support

## Channel Connectivity Issues

If a user reports problems with a messaging channel:

**General channel issues**:
- Verify the channel is enabled in **Settings > Channels**
- Check that the channel configuration is complete with all required credentials
- For two-way channels, ensure an assistant is assigned to handle responses

**Telegram**: Bot token must be valid (from @BotFather), bot must be added to the chat/group, webhook URL must be reachable.

**Slack**: App must be installed in the workspace, bot token needs required scopes, bot must be a member of the target channel.

**Discord**: Bot token must be valid, bot needs to be invited to the server with correct permissions, channel ID must be correct.

**Email**: SMTP server credentials must be configured, check for sending limits or spam filtering.

Direct the user to **Settings > Channels** to review and update their channel configuration.

## Browser Automation Issues

If web browsing via Chrome isn't working:

- The Chrome automation server must be configured by an administrator (in the MCP Servers settings)
- Chrome must be running and accessible on the server
- Basic web fetching is available as a fallback for simple page content retrieval

## Audio Issues

If speech-to-text or text-to-speech isn't working:

- Audio models must be configured in the instance settings by an administrator
- The audio service must be running and accessible
- Check whether the specific audio model is available on the system

Direct the user to check with their administrator about audio configuration.

## General Troubleshooting Approach

1. **Identify the symptom**: Ask the user specifically what isn't working
2. **Check status**: Look up processing status for content issues, or ask about configuration for other problems
3. **Look for patterns**: Is it one item or many? Did something recently change? Is it specific to one content type?
4. **Suggest actionable steps**: Point to specific settings pages, suggest reprocessing, or explain what might need to be configured
5. **Escalate gracefully**: If you can't diagnose the issue, suggest the user check server logs or contact their administrator