> ## Documentation Index
> Fetch the complete documentation index at: https://prismeai-legacy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Guide

> Detailed guide for diagnosing and resolving issues with Prisme.ai

<Frame>
  <img src="https://mintcdn.com/prismeai-legacy/jdOgS9ouJy0zTcFo/images/luke.png?fit=max&auto=format&n=jdOgS9ouJy0zTcFo&q=85&s=1aa992b9e8c6eb9e1424acb94bf79d7d" alt="Troubleshooting Guide" width="2024" height="1139" data-path="images/luke.png" />
</Frame>

# Troubleshooting Guide

This comprehensive troubleshooting guide provides detailed diagnostic procedures and solutions for issues you may encounter when using Prisme.ai. The guide is organized by product area and includes step-by-step instructions, diagnostic tools, and advanced solutions.

## Diagnostic Tools and Resources

Before diving into specific issues, familiarize yourself with these diagnostic tools available in Prisme.ai:

<CardGroup cols="2">
  <Card title="Activity Logs" icon="list-alt">
    Review detailed logs of system events, user actions, and errors

    * Path: Administration > Activity Logs
    * Filter by time, user, event type, and severity
  </Card>

  <Card title="System Health Dashboard" icon="heartbeat">
    Monitor system performance metrics and component status

    * Path: Administration > System Health
    * Check component status and resource utilization
  </Card>

  <Card title="Network Inspector" icon="network-wired">
    Analyze API calls and network activity

    * Available in browser developer tools
    * Check request/response patterns and errors
  </Card>

  <Card title="Debug Mode" icon="bug">
    Enable detailed debugging information

    * Path: User Profile > Preferences > Enable Debug Mode
    * Provides additional diagnostic information in UI
  </Card>
</CardGroup>

## AI Knowledge Troubleshooting

### Document Processing Issues

<Steps>
  <Step title="Check Document Status">
    Verify the current status of your document in AI Knowledge:

    * **Queued**: Document is waiting to be processed
    * **Processing**: Document is currently being processed
    * **Active**: Document has been successfully processed
    * **Error**: Processing failed
    * **Inactive**: Document is not being used for retrieval

    If status is "Error", check the specific error message for details.
  </Step>

  <Step title="Diagnose Document Format Issues">
    Some document formats may cause processing problems:

    1. Check if the document is in a supported format (PDF, DOCX, TXT, etc.)
    2. Verify the document isn't corrupted by opening it in its native application
    3. For PDFs, check if they're scanned documents or contain actual text
    4. Look for password protection or security settings that might block processing

    **Solution**: Convert problematic documents to a more standard format, remove password protection, or re-save from the original application.
  </Step>

  <Step title="Resolve Text Extraction Problems">
    If text isn't being extracted correctly:

    1. For scanned PDFs, enable OCR in the project settings
    2. Check for unusual fonts that might not be recognized
    3. Verify character encoding issues, especially with non-Latin scripts
    4. Look for image-heavy documents with limited text

    **Solution**: Enable OCR processing, use documents with embedded text rather than images of text, or manually extract and upload content as plain text.
  </Step>

  <Step title="Fix Chunking and Embedding Issues">
    If documents are processed but retrieval is poor:

    1. Adjust chunk size settings (smaller chunks for precise retrieval, larger for context)
    2. Modify chunk overlap (higher overlap prevents information fragmentation)
    3. Try different embedding models
    4. Check metadata extraction settings

    **Solution**: Experiment with different chunking settings based on your document type and use case. Dense text benefits from smaller chunks, while sparse text needs larger chunks.
  </Step>
</Steps>

### Query and Retrieval Problems

<Steps>
  <Step title="Diagnose Retrieval Failures">
    If queries don't return expected information:

    1. Check that documents containing the information are in "Active" status
    2. Verify the query uses keywords or phrases that match your documents
    3. Examine retrieved chunks to understand what's being returned
    4. Review metadata filters that might be excluding relevant documents

    **Solution**: Use the document explorer to search for expected content and verify it exists in your knowledge base.
  </Step>

  <Step title="Fix Relevance Issues">
    If retrieval returns irrelevant content:

    1. Enable query enhancement to improve search effectiveness
    2. Adjust the similarity threshold for retrieval
    3. Try different retrieval methods (semantic, keyword, hybrid)
    4. Adjust the number of chunks being retrieved

    **Advanced Solution**: Implement custom reranking logic by using AI Builder to create a post-processing step that sorts retrieved chunks by relevance.
  </Step>

  <Step title="Resolve Citation Problems">
    If citations are incorrect or missing:

    1. Check document metadata for proper source information
    2. Verify chunk size settings (too small can fragment citations)
    3. Examine LLM settings that control citation behavior
    4. Review system prompt instructions regarding citations

    **Solution**: Enhance your system prompt with explicit instructions for citation formatting and include source attribution requirements.
  </Step>
</Steps>

## AI Builder Troubleshooting

### Automation Flow Issues

<Steps>
  <Step title="Diagnose Trigger Problems">
    If automations aren't triggering:

    1. Verify event names match exactly between trigger and emitter
    2. Check scope settings (current socket, workspace, global)
    3. Examine conditions that might prevent triggering
    4. Confirm the automation is published and active

    **Debugging Technique**: Add a simple log action as the first step in your automation to confirm it's being triggered.
  </Step>

  <Step title="Resolve Data Flow Issues">
    If data isn't flowing correctly through your automation:

    1. Use `console.log` or similar logging to inspect data at each step
    2. Check for type mismatches (string vs number, object vs array)
    3. Verify variable names and paths are correct (case sensitivity matters)
    4. Look for null or undefined values that might cause errors

    **Solution**: Add data validation steps and type checking to ensure data consistency throughout the flow.
  </Step>

  <Step title="Fix External Integration Problems">
    For issues with external API calls:

    1. Test the API endpoint independently using Postman or similar tools
    2. Verify authentication credentials are valid and not expired
    3. Check request format matches API requirements
    4. Examine network logs for detailed error responses

    **Advanced Solution**: Implement retry logic with exponential backoff for transient failures, and add comprehensive error handling for different API response codes.
  </Step>
</Steps>

### Custom Code Troubleshooting

<Steps>
  <Step title="Debug JavaScript Errors">
    For issues in custom code functions:

    1. Use `console.log` statements to trace execution flow
    2. Check for syntax errors or typos
    3. Verify variable scopes and closures
    4. Test functions with simplified inputs

    **Debugging Technique**: Create a separate test automation that calls your custom function with controlled inputs to isolate the issue.
  </Step>

  <Step title="Resolve Timeout Issues">
    If functions are timing out:

    1. Check for infinite loops or recursive calls
    2. Look for blocking operations that take too long
    3. Verify external API calls include proper timeout handling
    4. Consider breaking large functions into smaller, chainable functions

    **Solution**: Implement asynchronous processing patterns and avoid synchronous blocking operations.
  </Step>

  <Step title="Fix Memory or Performance Issues">
    For code that runs slowly or consumes excessive resources:

    1. Look for inefficient algorithms or data structures
    2. Check for memory leaks from accumulated objects
    3. Verify you're not processing unnecessarily large datasets
    4. Consider pagination or streaming for large data operations

    **Advanced Solution**: Implement memoization for expensive calculations, use generators for processing large datasets, and optimize loops and data transformations.
  </Step>
</Steps>

## Self-Hosted Deployment Troubleshooting

### Installation and Startup Issues

<Steps>
  <Step title="Diagnose Kubernetes Deployment Failures">
    If pods are failing to start:

    1. Check pod status: `kubectl get pods -n prisme`
    2. Examine pod events: `kubectl describe pod [pod-name] -n prisme`
    3. View container logs: `kubectl logs [pod-name] -n prisme`
    4. Verify persistent volume claims are bound

    **Common Issues**: Resource constraints, image pull failures, configuration errors, or volume mounting problems.
  </Step>

  <Step title="Resolve Configuration Errors">
    For issues related to configuration:

    1. Check Helm values for correctness: `helm get values prisme -n prisme`
    2. Verify environment variables and secrets
    3. Examine ConfigMap and Secret resources
    4. Check for syntax errors in YAML files

    **Solution**: Compare against reference configuration files, use `helm lint` to check for YAML errors, and verify all required values are provided.
  </Step>

  <Step title="Fix Connectivity Issues">
    If services can't communicate:

    1. Verify network policies allow required traffic
    2. Check service definitions are correct
    3. Test connectivity between pods using debug containers
    4. Examine DNS resolution within the cluster

    **Advanced Solution**: Deploy a network debugging pod to trace routes and test connectivity between services.
  </Step>
</Steps>

### Performance and Scaling Issues

<Steps>
  <Step title="Diagnose Resource Constraints">
    If the system is slow or unresponsive:

    1. Check CPU and memory usage: `kubectl top pods -n prisme`
    2. Examine node resources: `kubectl top nodes`
    3. Look for throttling in container logs
    4. Monitor database performance metrics

    **Solution**: Adjust resource requests and limits in Helm values to allocate more resources to constrained components.
  </Step>

  <Step title="Resolve Database Performance Issues">
    For database-related slowdowns:

    1. Check database connection pools and active connections
    2. Examine slow query logs
    3. Monitor storage performance (IOPS, latency)
    4. Verify indexing is appropriate for query patterns

    **Advanced Solution**: Implement database sharding, optimize indexes, or scale database resources.
  </Step>

  <Step title="Fix Scaling Problems">
    If the system doesn't scale properly:

    1. Verify Horizontal Pod Autoscaler configuration
    2. Check if load balancing is working correctly
    3. Monitor scaling events and look for errors
    4. Examine resource quotas that might limit scaling

    **Solution**: Adjust autoscaling parameters, implement more efficient resource utilization, or adjust quota limits.
  </Step>
</Steps>

## Data Management Troubleshooting

### Data Import and Export Issues

<Steps>
  <Step title="Diagnose Import Failures">
    If data imports are failing:

    1. Check the format of your import file (CSV, JSON, etc.)
    2. Verify field mappings match expected schema
    3. Look for encoding issues, especially with special characters
    4. Check for size limitations being exceeded

    **Solution**: Pre-process import files to ensure correct formatting, validate against the expected schema before importing, and split large imports into smaller batches.
  </Step>

  <Step title="Resolve Export Problems">
    For issues with data exports:

    1. Verify export permissions
    2. Check for timeout issues with large exports
    3. Examine file format compatibility
    4. Verify destination storage has sufficient space

    **Solution**: Use paginated exports for large datasets, export to cloud storage for very large data, or use background export jobs rather than synchronous exports.
  </Step>
</Steps>

### Data Integration Issues

<Steps>
  <Step title="Fix Sync Problems">
    If data synchronization is failing:

    1. Check authentication credentials for external systems
    2. Verify API endpoints are accessible
    3. Look for rate limiting or throttling
    4. Examine data mapping and transformation errors

    **Solution**: Implement incremental sync strategies, add robust error handling with retries, and set up monitoring for sync processes.
  </Step>

  <Step title="Resolve Data Consistency Issues">
    If data appears inconsistent:

    1. Check for race conditions in parallel updates
    2. Verify transaction boundaries are appropriate
    3. Look for caching issues that might show stale data
    4. Examine error handling in update processes

    **Advanced Solution**: Implement optimistic concurrency control, use event sourcing patterns for critical data, or add data validation at multiple levels.
  </Step>
</Steps>

## Additional Resources

If you're still experiencing issues after following this troubleshooting guide:

<CardGroup cols="2">
  <Card title="Contact Support" icon="headset" href="/resources/support/contact">
    Get personalized assistance from our support team
  </Card>

  <Card title="Community Forum" icon="users" href="https://prisme-ai.discourse.group">
    Connect with other users and share solutions
  </Card>

  <Card title="Common Issues" icon="bug" href="/resources/support/common-issues">
    Quick solutions to frequently encountered problems
  </Card>

  <Card title="Training Programs" icon="graduation-cap" href="/resources/support/training">
    Enhance your skills with our training offerings
  </Card>
</CardGroup>

## Submitting an Effective Support Request

When contacting support, include these details for faster resolution:

* Detailed description of the issue
* Steps to reproduce
* Error messages (exact text)
* Screenshots or screen recordings
* Log files when available
* Environment details (browser, OS, deployment type)
* Recent changes that might be related to the issue