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

# Fix Model Connection Errors

> Diagnose and resolve Nextedy POWERSHEET connection failures that prevent the sheet from loading data when the data model cannot be reached or is misconfigured.

export const LastReviewed = ({date}) => {
  if (!date) return null;
  const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", {
    year: "numeric",
    month: "long",
    day: "numeric",
    timeZone: "UTC"
  });
  return <p className="mt-10 text-sm text-gray-400 dark:text-zinc-500 not-prose">
      Last reviewed on {formatted}
    </p>;
};

## Identify the Error

Model connection errors typically appear when opening a powersheet document. The sheet displays a loading error or the connection status shows **Failed** in the administration interface. Common symptoms include:

* Sheet shows a blank area or error dialog on load
* Connection status in **Administration > Nextedy Powersheet** shows "Failed" instead of "Active"
* Configuration loads but no data appears in the sheet

<Steps>
  <Step title="Verify the Model Path in Sheet Configuration">
    The `sources.model` property in your sheet configuration must match the name of your data model file. Open your sheet configuration YAML and check the `sources` section:

    ```yaml theme={null}
    sources:
      - model: my-custom-model    # Must match your model file name
        from: UserNeed
        expand:
          - systemRequirements.systemRequirement
    ```

    <Warning title="Model name must match exactly">
      The `sources.model` property must match your custom data model name -- not the default `rtm`. If you created a model named `my-project-model`, the value must be `my-project-model`, not `rtm` or `model`.
    </Warning>
  </Step>

  <Step title="Check the Model Path Resolution">
    Powersheet resolves model paths using these rules:

    | Model Value             | Resolved Path                            |
    | ----------------------- | ---------------------------------------- |
    | `my-model`              | `{projectId}/my-model` (current project) |
    | `otherProject/my-model` | `otherProject/my-model` (cross-project)  |
    | `/my-model`             | `_global/my-model` (global scope)        |

    Verify that your model file exists at the resolved path by navigating to **Administration > Nextedy Powersheet > Data Models**.

    <Warning title="Project-local models silently override same-name global models">
      If a global model and a project-local model share the same name, the project-local copy takes precedence -- the sheet may be reading a different model than you expect, with no error. If you intended to use the global model, check for and remove any project-level copy with the same name. See [Troubleshooting FAQ: global vs. project-level configuration](/powersheet/faq/troubleshooting) for details.
    </Warning>
  </Step>

  <Step title="Verify Connection Status">
    Connections go through three lifecycle states:

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/guides/troubleshooting/fix-model-connection-errors/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=8f66839910c34077026de2c9c6aa14eb" alt="diagram" style={{ width: "500px", maxWidth: "100%" }} width="500" height="80" data-path="powersheet/diagrams/guides/troubleshooting/fix-model-connection-errors/diagram-1.svg" />
    </Frame>

    * **Active**: Connection is operational and serving data
    * **Disabled**: Connection intentionally turned off by an administrator
    * **Failed**: Connection encountered an error during startup or restart

    If the status is **Failed**, the data model configuration contains an error that prevented initialization.
  </Step>

  <Step title="Validate the Data Model YAML">
    Common data model errors that cause connection failures:

    1. **Invalid YAML syntax** -- Check for indentation errors, missing colons, or stray characters
    2. **Missing `domainModelTypes`** -- The root `domainModelTypes` key must exist
    3. **Duplicate property names** -- Entity types cannot have duplicate property names within the same type
    4. **Invalid `polarionType` references** -- Each `polarionType` must match an existing Polarion work item type

    ```yaml theme={null}
    # Correct structure
    domainModelTypes:
      UserNeed:
        polarionType: requirement
        properties:
          description:
          severity:
    ```

    <Tip title="Save triggers automatic restart">
      When you save a connection configuration, Powersheet automatically restarts the connection to apply changes. Check the updated status after saving to confirm the fix.
    </Tip>
  </Step>

  <Step title="Verify Document Binding">
    Ensure the document is bound to the correct connection. Open the document settings and verify:

    * The source references a valid connection ID
    * The `from` field in the source query specifies a valid entity type from the data model

    ```yaml theme={null}
    sources:
      - model: my-custom-model
        from: UserNeed              # Must be a domainModelTypes key
        expand:
          - systemRequirements.systemRequirement
    ```

    <Warning title="Entities configuration validation">
      Powersheet validates entity configurations server-side. If duplicate property names are detected, an error dialog will appear and the connection will not be created or restarted.
    </Warning>
  </Step>
</Steps>

## Verification

After applying your fix:

1. Save the data model and sheet configuration
2. Navigate to **Administration > Nextedy Powersheet** and confirm the connection status shows **Active**
3. Open the powersheet document
4. You should now see data loading in the sheet without errors

## See Also

* [Validate Your Data Model](/powersheet/guides/data-model/validate-model) -- comprehensive model validation steps
* [Configure Sources](/powersheet/guides/sheet-configuration/configure-sources) -- set up source queries and expansion paths
* [Creating Your First Data Model](/powersheet/getting-started/first-data-model) -- step-by-step model creation
* [Fix Type Name Errors](/powersheet/guides/troubleshooting/fix-type-name-errors) -- related entity type naming issues

***

<LastReviewed date="2026-07-02" />