---
title: Troubleshooting
slug: piedpiper/troubleshooting
createdAt: 2026-02-10T13:26:51.733Z
---

# Troubleshooting Guide for Embedded Analytics & Reporting Builder

This guide provides solutions for common issues encountered by users of the Embedded Analytics & Reporting Builder. Follow the steps below to diagnose and resolve problems effectively.

## Common Issues

### Unable to Connect to Data Source

- **Solution**: Ensure that API keys or database credentials are correctly configured in the data source settings. Double-check firewall settings that might be blocking access. Consult the documentation specific to your data source for connection best practices.

### Reports Not Displaying

- **Solution**: Verify that the correct data source is linked to the report. Check if there are any errors or filters wrongly applied in the report builder that might prevent data from showing.

### Poor Performance During Report Generation

- **Solution**: Utilize query caching and pre-aggregated data tables. Review the analytics dashboard to identify slow queries and optimize them by adding indexes or modifying the SQL logic.

## Installation Problems

### Failed Deployment on AWS/GCP

- **Solution**: Double-check the cloud environment settings such as IAM permissions and security groups. Ensure that Docker and Kubernetes are correctly configured for deployment.

### Difficulty with On-Premise Setup

- **Solution**: Ensure hardware meets the minimum requirements specified in the installation documentation. Confirm all network settings permit access between nodes.

## Configuration Errors

### Incorrect White-Label Customization

- **Solution**: Verify CSS/theme customization files for syntax errors. Ensure your brand's assets like logos and fonts are uploaded in supported formats.

### Security & Permissions Issues

- **Solution**: Review role-based access control settings in the admin panel. Make sure row-level security settings align with your organizational data policies.

## Runtime Issues

### Dashboard Not Refreshing in Real-Time

- **Solution**: Check the data source's real-time capabilities. Upgrade the plan to allow real-time data refresh if applicable or check API limits and increase frequency settings.

### Crashes on Report Builder UI

- **Solution**: Update to the latest version of the software. Report builders might face issues if there are rendering conflicts; ensure the browser is up-to-date and cache is cleared.

## Diagnostic Procedures

### Log Analysis

- **Solution**: Analyze error logs in the system’s backend to identify patterns and recurring issues. Utilize tools like Loggly or Splunk for advanced log management.

## Step-by-Step Troubleshooting

### Error Codes & Meanings

- Review the specific error codes in the admin dashboard for detailed causes and solutions. Maintain a spreadsheet for quick reference and FAQs updates.

## FAQs & Community Solutions

### How to Share Reports with External Users?

- **Solution**: Utilize shareable links with permission controls. For further details, refer to the user community forum.

### How Do I Integrate with Custom Data Connectors?

- **Solution**: Consult the developer documentation for API-based data ingestion setup. Join community discussions for plug-and-play solutions that others have found useful.

## Contact & Support

### Need Additional Help?

- Reach out to our support team via the portal [support@example.com](mailto\:support@example.com) or visit the support page for live chat assistance. Check our online forums for community-driven tips and solutions.

***

If further issues persist after following this guide, consider opening a support ticket to get personalized assistance.