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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.