tomevault-io Troubleshooting Guide
Content Processing Pipeline
When content is added to Eclaire, it goes through a processing pipeline:
- Queued (pending) — Item is saved and waiting for a worker to pick it up
- Processing — A worker is actively working on it (extracting text, generating thumbnails, etc.)
- Completed — Processing finished successfully
- Failed — Processing encountered an error
- 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
- Identify the symptom: Ask the user specifically what isn't working
- Check status: Look up processing status for content issues, or ask about configuration for other problems
- Look for patterns: Is it one item or many? Did something recently change? Is it specific to one content type?
- Suggest actionable steps: Point to specific settings pages, suggest reprocessing, or explain what might need to be configured
- Escalate gracefully: If you can't diagnose the issue, suggest the user check server logs or contact their administrator
Source: eclaire-labs/eclaire — distributed by TomeVault.