Skip to main content

Troubleshooting Guide

This guide addresses common issues you might encounter while using Data Neuron and provides solutions to resolve them.

Common Issues and Solutions​

1. Installation Problems​

Issue: Unable to install Data Neuron or its dependencies.

Solution:

  • Ensure you're using Python 3.7 or later.
  • Try upgrading pip: pip install --upgrade pip
  • If you're using a specific database, install with the appropriate extras: pip install dataneuron[postgres]

2. Database Connection Errors​

Issue: Unable to connect to the database.

Solution:

  • Double-check your database.yaml configuration and the name yml or yaml.
  • Ensure the database server is running and accessible.
  • Verify network settings and firewall rules.

3. Query Generation Failures​

Issue: Data Neuron is unable to generate SQL for your natural language query.

Solution:

  • Review and optimize your semantic layer (context files).
  • Try rephrasing your query to be more specific.
  • Check if the entities in your query are properly defined in the context.

4. Unexpected Query Results​

Issue: Query results don't match expectations.

Solution:

  • Review the generated SQL to ensure it matches your intent.
  • Check your data for any inconsistencies.
  • Verify the semantic layer definitions for the relevant tables and columns.

5. Performance Issues​

Issue: Queries are taking too long to execute.

Solution:

  • Optimize your database indexes.
  • Review and optimize complex queries.
  • Consider caching frequently used query results.

Diagnostic Steps​

  1. Enable Logging: Set log=True when initializing DataNeuron to get detailed logs.

  2. Check Versions: Ensure you're using the latest version of Data Neuron and its dependencies.

  3. Validate Context: Use the Data Neuron CLI to validate your context files:

    dnn --validate-context your_context_name

  4. Isolate the Problem: Try to reproduce the issue with a minimal example to isolate the problem.

Getting Help​

If you're still experiencing issues after trying these solutions:

  1. Check the Data Neuron documentation for more detailed information.
  2. Search for similar issues in the GitHub Issues section.
  3. If your problem persists, open a new issue on GitHub with a detailed description of the problem, steps to reproduce, and any relevant logs or error messages.

Remember to always keep your Data Neuron installation and context files up to date for the best performance and compatibility.