> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chartdb.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Common Issues

> Find solutions to common technical problems encountered while using ChartDB.

<AccordionGroup>
  <Accordion title="Invalid JSON Error During Import" icon="file-excel">
    This usually means ChartDB can't understand the format of the JSON data you're providing.

    **Possible Causes:**

    * **Incorrect JSON Syntax:** The JSON data might have syntax errors.
    * **Database Client Formatting:** Your database client might be outputting JSON in an unrecognized format.
    * **Truncated JSON:** For large schemas, your database client might cut off the JSON output.
    * **Copy-Paste Issues:** Errors can be introduced when pasting the JSON into ChartDB.

    **Troubleshooting Steps:**

    <Steps>
      <Step title="Verify JSON Syntax">
        Use an online JSON validator to check your exported JSON for syntax errors. Correct any errors found before importing into ChartDB.
      </Step>

      <Step title="Adjust Database Client Output Settings (SSMS/Azure Data Studio)">
        <Tip>This step is primarily for users using **SQL Server Management Studio (SSMS)** or **Azure Data Studio**.</Tip>

        Increase the character limit for query results in your database client:

        <Tabs>
          <Tab title="SSMS">
            1. Go to **Tools → Options**.
            2. Navigate to **Query Results → SQL Server → Results to Text**.
            3. Increase **Maximum number of characters displayed in each column**.
          </Tab>

          <Tab title="Azure Data Studio">
            1. Go to **File -> Preferences -> Settings** (or **Code -> Settings** on macOS).
            2. Search for `mssql.query.maxCharsToStore`.
            3. Set **Maximum Characters To Store** to a large value.
          </Tab>
        </Tabs>
      </Step>

      <Step title="Re-export and Re-import">
        After adjusting settings or correcting JSON syntax, re-run the ChartDB export query. Copy the **entire** JSON output again and paste it into ChartDB.
      </Step>

      <Step title="Try a Different Browser">
        Test importing the JSON in a different web browser to rule out browser-specific issues.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Missing Tables After Database Import" icon="table-rows">
    If your database has multiple schemas, ChartDB might not display all your tables immediately after import.

    **Possible Cause:**

    * **Default Schema Display:** By default, ChartDB only shows tables from the `public` schema. Tables in other schemas are hidden initially.

    **Solution:**

    To display tables from other schemas, you need to select them in the schema management panel.

    **Steps:**

    <Steps>
      <Step title="Select Schemas to Display">
        Go to the tables and fields pages and navigate to the "Managing Schemas" section to learn how to select schemas and display tables from those schemas.
        [Learn more about managing schemas](/docs/diagrams/tables-fields#managing-schemas)
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Missing Relationships After Database Import (PostgreSQL, SQL Server)" icon="diagram-project">
    Users importing PostgreSQL and SQL Server databases sometimes report that relationships between tables are not automatically detected and visualized.

    **Possible Causes:**

    * **Incomplete Foreign Key Definitions:** ChartDB relies on foreign key constraints. If these are missing or incorrect, relationships might not import.
    * **Query Limitations (Rare):** The import query might not fully capture relationship data in complex schemas.

    **Troubleshooting Steps:**

    <Steps>
      <Step title="Verify Foreign Key Constraints in your Database">
        Ensure foreign key constraints are correctly defined in your database. Use a database client to inspect table definitions.
      </Step>

      <Step title="Use Updated Import Query">
        Try using the updated import query provided by the ChartDB team for your specific database.
      </Step>

      <Step title="Manually Add Relationships in ChartDB">
        Create relationships manually within ChartDB using drag and drop, right-click, or the side panel.
      </Step>

      <Step title="Check for Naming Conventions">
        Unconventional naming of foreign key columns might hinder automatic detection.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Diagram Export to PNG/JPG/SVG Fails or Hangs" icon="file-image">
    Sometimes, exporting your diagram to image formats (PNG, JPG, SVG) might fail without a clear error message, or the process might hang.

    **Possible Causes:**

    * **Diagram Complexity:** Very large or complex diagrams can strain browser resources.
    * **Browser Limitations:**  Browser resource limits might prevent successful export.
    * **Browser Compatibility:**  Browser-specific issues might interfere with export.

    **Troubleshooting Steps:**

    <Steps>
      <Step title="Check Browser Console for Errors">
        Open your browser's developer console. Attempt export again. Check the console for JavaScript errors.
      </Step>

      <Step title="Try a Different Browser">
        Try exporting the diagram using a different web browser.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="ChartDB Slow or Crashing with Large Databases" icon="database">
    Working with very large database schemas can sometimes lead to performance issues or browser crashes.

    **Possible Causes:**

    * **Browser Resource Limits:**  Browsers have resource limitations when rendering large diagrams.
    * **ChartDB Optimization:** Current ChartDB version is optimized for moderately sized databases.

    **Recommendations for Handling Large Databases:**

    <Steps>
      <Step title="Import Only Necessary Schemas/Subsets">
        If possible, import only the schemas or subsets you need to visualize.
      </Step>

      <Step title="Simplify Diagrams">
        Break down very large diagrams into smaller, domain-specific diagrams.
      </Step>

      <Step title="Monitor Browser Performance">
        Observe browser resource usage (CPU, Memory) to identify limitations.
      </Step>
    </Steps>
  </Accordion>

  <Accordion title="Diagrams Disappear or are Lost After Browser Session" icon="floppy-disk-circle-xmark">
    Users sometimes report that their diagrams disappear after closing their browser.

    <Note>
      ChartDB cloud version automatically backs up your diagrams in the cloud, while the self-hosted version stores diagrams only in your browser's local storage and requires manual exports for backup.
      See our [Cloud vs Self-Hosted](/docs/cloud-vs-self-hosted) documentation for more details.
    </Note>

    **Possible Causes:**

    * **Browser Data Clearing:** Clearing browser data (cache, cookies, site data) can delete locally stored diagrams.
    * **Incognito/Private Browsing:** Private browsing modes usually clear local storage when the session ends.
    * **Browser Settings or Extensions:** Some settings or extensions might clear IndexedDB or site data.

    **Preventing Diagram Loss:**

    <Steps>
      <Step title="Understand Local Browser Storage">
        Diagrams are stored **locally in your web browser**.
      </Step>

      <Step title="Avoid Clearing Browser Data Unintentionally">
        Be cautious when clearing browser data. **Do not clear "Cookies and other site data"** to preserve diagrams.
      </Step>

      <Step title="Do Not Use Incognito/Private Browsing for Important Diagrams">
        Avoid using incognito mode for important diagrams.
      </Step>

      <Step title="Regularly Export Your Diagrams as Backups">
        **Regularly export your diagrams as JSON files.** Treat these files as backups.
      </Step>
    </Steps>
  </Accordion>
</AccordionGroup>