> ## 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 Relationship Errors

> Diagnose and resolve data model relationship configuration errors in Nextedy POWERSHEET, including invalid entity references, missing link roles, incorrect cardinality, and mismatched navigation properties.

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>;
};

## Symptom Quick Reference

Use this table to jump to the right fix based on the error you are seeing:

| Symptom                                         | Likely Cause                                       | Jump To                                                                                    |
| ----------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| Sheet fails to load after saving the data model | Invalid `from` or `to` entity reference            | [Step 1: Verify Entity Type References](#step-1-verify-entity-type-references)             |
| Navigation columns appear empty                 | Missing or wrong `direct`/`back` name              | [Step 2: Check Navigation Property Names](#step-2-check-navigation-property-names)         |
| Expansion path produces no child rows           | Navigation name mismatch between model and sources | [Step 3: Align Sources with Navigation Names](#step-3-align-sources-with-navigation-names) |
| Links not saved to Polarion                     | Invalid `linkRole` value                           | [Step 4: Verify the Link Role](#step-4-verify-the-link-role)                               |
| Wrong column behavior (multi vs. single)        | Cardinality does not match the actual relationship | [Step 5: Validate Cardinality](#step-5-validate-cardinality)                               |
| Second linked column shows nothing              | Missing `multiItem: true` on the column            | [Step 6: Fix Multi-Item Column Declarations](#step-6-fix-multi-item-column-declarations)   |

<Steps>
  <Step title="Verify Entity Type References">
    Every relationship must reference valid entity type names in its `from` and `to` fields. These names must exactly match keys defined under `domainModelTypes`, including capitalization.

    ```yaml theme={null}
    domainModelTypes:
      UserNeed:
        polarionType: user_need
        properties:
          description:
          severity:
      SystemRequirement:
        polarionType: sys_req
        properties:
          description:
          severity:

    relationships:
      - from: UserNeed              # Must match a domainModelTypes key exactly
        to: SystemRequirement       # Must match a domainModelTypes key exactly
        cardinality: many-to-many
        storage: linkedWorkItems
        linkRole: decomposes
        direct:
          name: userNeeds
        back:
          name: systemRequirements
    ```

    <Warning title="Case sensitivity matters">
      Entity type names are case-sensitive. `systemRequirement` and `SystemRequirement` are different values. If the `from` value does not match any `domainModelTypes` key, the source side of the relationship is broken. If the `to` value is wrong, the target side is broken. Double-check exact capitalization in both locations.
    </Warning>
  </Step>

  <Step title="Check Navigation Property Names">
    The `direct` and `back` sections each contain a `name` field that creates a navigation property on the respective entity type. These navigation property names are what you use in column binding paths and source expansion paths throughout the sheet configuration.

    * **`direct.name`** -- creates a forward navigation property on the `from` entity type (navigates toward the `to` entity)
    * **`back.name`** -- creates a reverse navigation property on the `to` entity type (navigates back toward the `from` entity)

    ```yaml theme={null}
    relationships:
      - from: UserNeed
        to: SystemRequirement
        cardinality: many-to-many
        storage: linkedWorkItems
        linkRole: decomposes
        direct:
          name: userNeeds              # Property on SystemRequirement pointing back to UserNeed
        back:
          name: systemRequirements     # Property on UserNeed pointing forward to SystemRequirement
    ```

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

    <Warning title="Missing navigation names">
      If either `direct` or `back` is missing its `name` field, the corresponding navigation property will not be created. Any column or expansion path that references that property name will silently return no data.
    </Warning>
  </Step>

  <Step title="Align Sources with Navigation Names">
    The `expand` entries in your sheet configuration sources must exactly match the navigation property names defined by `direct.name` or `back.name` in the data model. A mismatch here is one of the most common causes of empty expansion results.

    **Many-to-one (N:1) -- single-level expand:**

    ```yaml theme={null}
    # Data model: UserNeed -> Chapter, direct.name = "chapter"
    sources:
      - id: user_needs
        query:
          from: UserNeed
        expand:
          - name: chapter           # Must match direct.name exactly
    ```

    **One-to-many (1:N) -- collection expand:**

    ```yaml theme={null}
    # Data model: Chapter <- UserNeed, back.name = "userNeeds"
    sources:
      - id: chapters
        query:
          from: Chapter
        expand:
          - name: userNeeds         # Must match back.name exactly
    ```

    **Many-to-many (M:N) -- two-level expand through association:**

    ```yaml theme={null}
    # Data model: UserNeed <-> SystemRequirement, back.name = "systemRequirements"
    sources:
      - id: user_needs
        query:
          from: UserNeed
        expand:
          - name: systemRequirements          # Association level
            expand:
              - name: systemRequirement       # Target entity level
    ```

    <Tip title="Many-to-many requires two expand levels">
      Many-to-many relationships use an association entity between the two types. The source expand must go two levels deep: first the collection navigation property (e.g., `systemRequirements`), then the target entity within the association (e.g., `systemRequirement`). Forgetting the second level is a frequent cause of empty columns.
    </Tip>
  </Step>

  <Step title="Verify the Link Role">
    The `linkRole` must match a link role **ID** defined in your Polarion project configuration, not its display name.

    ```yaml theme={null}
    relationships:
      - from: UserNeed
        to: SystemRequirement
        cardinality: many-to-many
        storage: linkedWorkItems
        linkRole: decomposes          # Polarion link role ID, not display name
        direct:
          name: userNeeds
        back:
          name: systemRequirements
    ```

    To find valid link role IDs, go to **Administration > Work Items > Link Roles** in Polarion. The **ID** column shows the value to use in your data model YAML.

    <Tip title="Use Polarion link role IDs, not display names">
      The `linkRole` value is the link role **ID** (e.g., `decomposes`, `parent`), not the display name (e.g., "Decomposes", "Has Parent"). If the link role ID does not exist in the project, relationships will not persist when users save changes in the sheet.
    </Tip>
  </Step>

  <Step title="Validate Cardinality">
    The `cardinality` value must match the actual relationship between your entity types. Using the wrong cardinality causes incorrect UI behavior -- columns that should allow multiple selections only show one value, or vice versa.

    | Cardinality    | Source Expand                                                 | Column Binding                         | UI Behavior                   |
    | -------------- | ------------------------------------------------------------- | -------------------------------------- | ----------------------------- |
    | `many-to-one`  | `- name: chapter`                                             | `chapter`, `chapter.title`             | Single-value reference picker |
    | `one-to-many`  | `- name: userNeeds`                                           | `userNeeds`                            | Child rows (new sheet level)  |
    | `many-to-many` | `- name: systemRequirements` then `- name: systemRequirement` | `systemRequirements.systemRequirement` | Multi-item reference picker   |

    <Warning title="Cardinality affects column behavior">
      A many-to-one column displays a single-value reference picker. A one-to-many expand creates child rows in the sheet. A many-to-many column uses a multi-item picker with association entity binding. If you set the wrong cardinality, the sheet may render but users will encounter errors when trying to edit or save relationships.
    </Warning>
  </Step>

  <Step title="Fix Multi-Item Column Declarations">
    When a parent entity links to multiple work item types (for example, a `SystemRequirement` linked to both `DesignRequirement` and `DesignVerification`), the second linked column must include `multiItem: true` in the sheet configuration. This is a non-obvious requirement that frequently blocks first-time configurations.

    ```yaml theme={null}
    columns:
      designRequirements.designRequirement:
        title: Design Requirement
        list:
          search:
            - title
      designVerifications.designVerification:
        title: Design Verification
        multiItem: true               # Required for the second linked entity column
        list:
          search:
            - title
    ```

    <Tip title="Start with a single-item configuration">
      When setting up a new sheet, start with the simplest possible configuration -- one entity type, one relationship. Add additional linked columns incrementally. This approach makes it much easier to isolate which relationship definition is causing errors.
    </Tip>
  </Step>

  <Step title="Validate the Complete Configuration Chain">
    After making corrections, verify the full chain from data model through sources to columns:

    1. **Data model** -- confirm `from`/`to` match `domainModelTypes` keys, `linkRole` is a valid Polarion link role ID, and both `direct.name` and `back.name` are present
    2. **Sources** -- confirm each `expand` name matches a navigation property name from the data model, and many-to-many expands have two levels
    3. **Columns** -- confirm column binding paths use the correct dot-notation from the expand chain, and `multiItem: true` is set where needed
    4. **Storage** -- confirm `storage: linkedWorkItems` is used for Polarion link-based relationships
  </Step>
</Steps>

## Verification

After correcting the relationship configuration:

1. Save the data model YAML in **Administration > Nextedy Powersheet > Data Models**
2. Open a powersheet document that uses this data model
3. Expand a row with related entities
4. You should now see child entities appearing correctly under the expansion path, and the reference picker columns displaying valid choices

## See Also

* [Configure a Relationship](/powersheet/guides/data-model/configure-relationship) -- complete relationship setup guide
* [Create Bidirectional Links](/powersheet/guides/data-model/create-bidirectional-links) -- setting up two-way navigation
* [Configure Many-to-Many Relationships](/powersheet/guides/data-model/configure-many-to-many) -- many-to-many relationship configuration
* [Fix Multi-Item Column Errors](/powersheet/guides/troubleshooting/fix-multi-item-errors) -- troubleshooting multi-item column issues
* [Fix Type Name Errors](/powersheet/guides/troubleshooting/fix-type-name-errors) -- resolving entity type naming mismatches
* [Data Model Reference](/powersheet/reference/data-model/index) -- complete data model YAML reference

***

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