.. _troubleshooting: =============== Troubleshooting =============== If you experience any bugs or unexpected behavior, please let us know. We will do our best to help you. .. include:: ../../_includes/security_warning.rst Did you find a bug? ------------------- When you encounter a bug using the WebUI, you can use the built-in reporting feature: Click the :ref:`"Report this issue" button ` included in error banners. This automatically generates a diagnostic file and composes a pre-filled email support request. .. admonition:: Reporting bugs :class: tip To report a bug, **please contact our support at** `support@sunpeek.org `_. Please include: - **Description** of what you were doing when the error occurred and what behavior you expected. - **Steps to reproduce** the problem - **Screenshots**, if helpful - The **diagnostic file** :ref:`debug_dump.json `, auto-generated by :ref:`"Report this issue" ` Thank you for helping us improve this open-source software! .. note:: Want to contribute to resolving a bug? See the :ref:`Contributing Guide ` for how to search existing issues and submit new ones on GitLab. How Errors Are Displayed ------------------------- When SunPeek encounters an error, it displays an error banner with the following components: - **Bug icon**: A red bug icon (mdi-bug) in the top left - **Status code** header: Indicates the error type (e.g., "Error 400", "Error 0") - **Report this issue** button: See :ref:`report-this-issue-button` for details - **Message** field: User-friendly explanation of what went wrong - **Detail** field: Technical information to help diagnose the issue - **Dismiss** icon: "X" icon (top right) to close the banner .. _error-banner-example: .. figure:: ../../_static/sunpeek_error-banner_400__no_button.png :alt: Example error banner showing status code, message, detail, and action buttons :align: center :width: 100% Example error banner with all components. For long error details (more than 300 characters), a "SHOW DETAILS" button appears in the error banner. Clicking it opens a modal dialog displaying the full error details: .. figure:: ../../_static/sunpeek_error-banner_400__with_button.png :alt: Error banner with Show Details button for long error messages :align: center :width: 100% .. figure:: ../../_static/sunpeek_error-show-details.png :alt: Modal dialog showing formatted detailed error information :align: center :width: 80% Dialog with detailed error information after clicking the "SHOW DETAILS" button. Connection Problems ------------------- If the WebUI cannot connect to the backend API or database, you'll see a connection status page showing which components are unreachable and suggesting what to do. This typically happens when: - Docker containers are not running or have crashed - Network connectivity issues prevent the frontend from reaching the backend - The backend service is starting up (may take a few minutes) - AdBlockers or VPN clients interfere with local connections .. figure:: ../../_static/sunpeek_error-connection-status.png :alt: Connection status page showing frontend, backend, and database connectivity :align: center :width: 80% Connection status page displaying connectivity issues and troubleshooting guidance. Reporting Problems ------------------ .. _report-this-issue-button: "Report this issue" button ^^^^^^^^^^^^^^^^^^^^^^^^^^^ Error banners include a *"Report this issue" button* that performs a two-step process: 1. Downloads a ``debug_dump.json`` file containing system diagnostics. 2. Opens your email client with a pre-filled support request including the diagnostics file. .. figure:: ../../_static/sunpeek_error-banner__report_button.png :alt: Report this issue button in error banner :align: center :width: 60% "Report this issue" button in an error banner. .. _debug-dump-file: Debug dump file ^^^^^^^^^^^^^^^ The ``debug_dump.json`` file contains system information that helps diagnose problems, including: - SunPeek version and configuration - Browser information - Error details and stack traces - Plant configuration (if applicable) What You Can Do ---------------- Here are general troubleshooting actions you can take when encountering errors: 1. **Dismiss and retry**: Close the error banner and try the operation again. Temporary issues sometimes resolve themselves (e.g., network hiccups, transient server problems). 2. **Check your configuration**: For validation errors, review the affected settings; the error detail often indicates which field needs attention. For data upload error handling details, see :ref:`06_upload`. 3. **Check Docker logs**: For network or server errors, inspect container logs for additional information using ``docker logs ``. Look for error messages, stack traces, or warnings that provide more context about the problem. 4. **Report the issue**: If the error persists or is unclear, use the :ref:`built-in reporting feature `. Common Errors ------------- .. dropdown:: Network Error (Status 0) **Meaning**: The frontend cannot reach the backend API. This usually means the database is offline or the API is unreachable. **What to do**: - Check that Docker containers are running: ``docker ps`` - Review Docker logs for additional information: ``docker logs `` - Verify network connectivity between frontend and backend .. dropdown:: Bad Request (Error 400) **Meaning**: The request was valid but could not be processed by the backend due to invalid configuration, missing data, or data validation errors. This commonly occurs with: - Invalid datetime formats or timezone-naive timestamps - Missing required fields in configuration - Data upload issues (missing timestamps, mismatched sensor names) - Invalid Power Check settings (e.g., negative values, out-of-range parameters) **What to do**: - Check the error detail; it provides specific information about what's invalid - Verify datetime formats: Use ISO 8601 format with timezone (e.g., ``2024-01-01T12:00:00+01:00``) or include a separate timezone parameter - Review configuration values: Ensure all required fields are filled and values are within valid ranges. Also check sensor information (e.g. radiation sensor orientation) - Data uploads: Verify that CSV columns match sensor names and contain valid timestamps - If the error persists, use the *"Report this issue"* button to get help .. dropdown:: Server Error (Status 500) **Meaning**: A critical error occurred in the backend API while processing your request. **What to do**: - Check Docker logs for detailed error information and stack traces - Report the issue using the **"Report this issue"** button .. dropdown:: SensorDataNotFoundError **Meaning**: A sensor is configured in the plant configuration, but the underlying data column is missing or misnamed in the database. **What to do**: - Ensure data has been uploaded for the sensor (database columns are only created once data is uploaded) - Verify sensor column names match your data files exactly - Check the sensor mapping configuration .. note:: This is the most common error when using SunPeek as a web application. It typically occurs when sensors are added to configuration before uploading data for them. .. dropdown:: NoDataError **Meaning**: No data is available in the selected time range for the requested analysis. **What to do**: - Adjust the date range to match your uploaded data - Upload additional data if needed - Verify data was uploaded successfully .. dropdown:: ConfigurationError **Meaning**: The plant configuration contains invalid or inconsistent settings. **What to do**: - Review plant configuration settings carefully - Check the error detail for specific field issues - Ensure all required fields are filled in correctly - Verify units, formats, and value ranges .. dropdown:: TimeZoneError **Meaning**: There is a timezone mismatch or invalid timezone information in your data or configuration. **What to do**: - Check timezone settings in plant configuration - Verify data file timestamps are in the expected timezone - Ensure timezone strings are valid (e.g., "UTC", "Europe/Vienna") .. dropdown:: PowerCheckError **Meaning**: The Power Check analysis cannot be performed with the current configuration or data. **What to do**: - Ensure all required sensors are mapped correctly - Verify data exists for the selected time range - Check that sensor data is valid (no NaN values, reasonable ranges) - See the Sensor Data page for data quality information .. dropdown:: Unexpected calculation error **Meaning**: An error occurred during internal calculations (virtual sensors, Power Check, D-CAT). This is typically related to unexpected numeric problems or issues in external libraries used by specific calculations. **What to do**: - Use the **"Report this issue"** button to help improve software robustness - Check Docker logs for the full error trace: ``docker logs `` - The ``debug_dump.json`` file will be automatically included when you report the issue .. note:: The full error trace is recorded in the backend log files. Your system administrator can inspect these logs for detailed diagnostic information.