Troubleshooting Guide

Detailed guide for diagnosing and resolving issues with Prisme.ai

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:

Activity Logs

Review detailed logs of system events, user actions, and errors

• Path: Administration > Activity Logs
• Filter by time, user, event type, and severity

System Health Dashboard

Monitor system performance metrics and component status

• Path: Administration > System Health
• Check component status and resource utilization

Network Inspector

Analyze API calls and network activity

• Available in browser developer tools
• Check request/response patterns and errors

Debug Mode

Enable detailed debugging information

• Path: User Profile > Preferences > Enable Debug Mode
• Provides additional diagnostic information in UI

Knowledges Troubleshooting

Document Processing Issues

1. Check Document Status

   Verify the current status of your document in Knowledges:

   • 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.

2. 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.

3. 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.

4. 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.

Query and Retrieval Problems

1. 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.

2. 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 Builder to create a post-processing step that sorts retrieved chunks by relevance.

3. 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.

Builder Troubleshooting

Automation Flow Issues

1. 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.

2. 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.

3. 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.

Custom Code Troubleshooting

1. 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.

2. 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.

3. 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.

Self-Hosted Deployment Troubleshooting

Installation and Startup Issues

1. 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.

2. 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.

3. 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.

Performance and Scaling Issues

1. 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.

2. 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.

3. 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.

Data Management Troubleshooting

Data Import and Export Issues

1. 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.

2. 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.

Data Integration Issues

1. 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.

2. 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.

Additional Resources

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

Contact Support

Get personalized assistance from our support team

Community Forum

Connect with other users and share solutions

Common Issues

Quick solutions to frequently encountered problems

Training Programs

Enhance your skills with our training offerings

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