> ## 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.

# Debug Custom Field Issues

> Diagnose and resolve Nextedy POWERSHEET problems where Polarion custom fields do not appear, display incorrectly, or fail to save in the sheet.

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 Symptom

Custom field issues typically present in one of these ways:

| Symptom                             | Likely Cause                         | Jump to                                                 |
| ----------------------------------- | ------------------------------------ | ------------------------------------------------------- |
| Column is completely empty          | Missing data model property          | [Step 1](#step-1-verify-the-data-model-property)        |
| Column does not appear at all       | Missing sheet configuration column   | [Step 2](#step-2-verify-the-sheet-configuration-column) |
| Values display but cannot be edited | Read-only flag or permission issue   | [Step 4](#step-4-check-read-only-status)                |
| Field type renders incorrectly      | Type mapping mismatch                | [Step 3](#step-3-verify-type-mapping)                   |
| Edits do not persist after save     | Property name mismatch with Polarion | [Step 5](#step-5-debug-save-failures)                   |

<Steps>
  <Step title="Verify the Data Model Property">
    Custom fields must be declared as properties on the correct entity type in the data model YAML. If the property is missing, the column will appear blank even though work items contain values in Polarion.

    Open your data model file and confirm the custom field is listed under the appropriate entity type:

    ```yaml theme={null}
    domainModelTypes:
      SystemRequirement:
        polarionType: systemRequirement
        properties:
          description:
          severity:
          priority:
          c_verificationMethod:    # Custom field property
    ```

    <Warning title="Property name must match the Polarion custom field ID exactly">
      Polarion custom fields use the `c_` prefix by convention (e.g., `c_riskLevel`, `c_verificationMethod`). The property name in the data model must match the **field ID**, not the display label. Confirm the exact field ID in **Administration > Work Items > Custom Fields**.
    </Warning>

    If the custom field belongs to a different Polarion work item type than the entity's default, make sure the `polarionType` mapping is set correctly. When the data model entity name differs from the Polarion work item type ID, specify `polarionType` to establish the mapping:

    ```yaml theme={null}
    domainModelTypes:
      DesignOutput:
        polarionType: designOutput    # Maps to Polarion type ID
        properties:
          c_designCategory:
    ```
  </Step>

  <Step title="Verify the Sheet Configuration Column">
    After confirming the data model property exists, verify that a corresponding column is defined in your sheet configuration. Both the model property and the sheet column are required for the field to appear.

    <Frame>
      <img src="https://mintcdn.com/none-17b4493f/-WiVljKlDztH36bB/powersheet/diagrams/guides/troubleshooting/debug-custom-field-issues/diagram-1.svg?fit=max&auto=format&n=-WiVljKlDztH36bB&q=85&s=07f78fdab30bd620cd5b120b16d99fc9" alt="diagram" style={{ width: "520px", maxWidth: "100%" }} width="520" height="130" data-path="powersheet/diagrams/guides/troubleshooting/debug-custom-field-issues/diagram-1.svg" />
    </Frame>

    Add the column to the sheet configuration using the property name as the column key:

    ```yaml theme={null}
    columns:
      c_verificationMethod:
        title: "Verification Method"
        width: 150
    ```

    For custom fields on **related entities** (accessed via an expansion path), use the full binding path through the relationship:

    ```yaml theme={null}
    columns:
      systemRequirements.systemRequirement.c_verificationMethod:
        title: "Verification Method"
        width: 180
    ```

    <Warning title="Common first-time mistake: starting too complex">
      New users often jump straight to multi-level configurations with custom fields on related entities. Start with a minimal single-entity setup and verify each custom field works before extending to relationships. This approach makes it much easier to isolate which part of the configuration is causing problems.
    </Warning>
  </Step>

  <Step title="Verify Type Mapping">
    Powersheet automatically maps Polarion field types to appropriate data types through the metadata system. If your custom field appears but renders incorrectly (for example, a date showing as plain text), check that Polarion recognizes the field type correctly.

    The automatic type conversion supports these Polarion types:

    | Polarion Type        | Mapped Behavior        | Common Issue                          |
    | -------------------- | ---------------------- | ------------------------------------- |
    | `String`             | Text input             | Renders correctly by default          |
    | `Integer`            | Numeric input          | Ensure saved value is numeric         |
    | `Float` / `Currency` | Decimal input          | Check decimal precision in Polarion   |
    | `Boolean`            | Checkbox toggle        | Value must be `true` or `false`       |
    | `Date` / `DateOnly`  | Date picker            | Format mismatch if field type changed |
    | `Text`               | Rich text / multi-line | May need formatter for display        |

    <Tip title="Enum fields require matching values">
      If your custom field uses an enumeration type, the enum values in Polarion must be correctly defined. Powersheet reads the allowed values from the Polarion type system. If the dropdown is empty or shows unexpected options, verify the enum definition in **Administration > Enumerations** for the correct work item type and project scope.
    </Tip>
  </Step>

  <Step title="Check Read-Only Status">
    If the column appears but cannot be edited, check these areas in order:

    **1. Column-level `isReadOnly` flag**

    Verify the column is not explicitly set to read-only in the sheet configuration:

    ```yaml theme={null}
    columns:
      c_verificationMethod:
        title: "Verification Method"
        width: 150
        isReadOnly: false    # Default is false; remove or set explicitly
    ```

    <Tip title="Default is editable">
      The `isReadOnly` property defaults to `false`. If you do not set it, the column is editable. If someone set `isReadOnly: true` for debugging and forgot to revert it, the column will silently become read-only.
    </Tip>

    **2. Entity type permissions**

    Check that the entity type's permissions in the data model allow editing. Navigate to **Administration > Nextedy Powersheet > Data Models** and confirm the entity type does not restrict write access for the current user's role.

    **3. Expansion path columns**

    Columns that display properties from related entities via an expansion path are read-only by default. Editing through expansion paths requires explicit configuration of the relationship's write behavior.

    **4. System fields**

    Built-in fields like `id` and `outlineNumber` are always read-only regardless of configuration.
  </Step>

  <Step title="Debug Save Failures">
    If you can edit a custom field in the sheet but changes do not persist after saving, the issue is usually a mismatch between the property name in the data model and the actual Polarion custom field ID.

    **Check the browser console** for error responses during save. Powersheet returns structured error information with a `message` field describing what went wrong and an HTTP `statusCode`.

    **Common save failure causes:**

    1. **Property name typo** -- The property key in the data model must match the Polarion field ID character-for-character, including the `c_` prefix and exact casing
    2. **Wrong entity type** -- The custom field is defined on a different Polarion work item type than the one mapped by `polarionType`
    3. **Field not enabled for the project** -- The custom field exists globally but is not enabled for the current project's work item type configuration

    <Accordion title="Silent blank columns from `sources.model` mismatch">
      If all custom field columns are blank across the entire sheet, verify that the `sources.model` property in your sheet configuration matches the name of your custom data model file. A common mistake is leaving the default value when you have created a model with a different name. The model name in `sources` must match exactly.
    </Accordion>

    ```yaml theme={null}
    sources:
      - model: my-custom-model    # Must match your .yaml model file name
    ```
  </Step>

  <Step title="Multi-Item Custom Fields">
    When an entity type links to multiple work item types (for example, `SystemRequirement` links to both `DesignOutput` and `DesignVerification`), the second linked column must use `multiItem: true` in the sheet configuration.

    ```yaml theme={null}
    columns:
      designOutputs.designOutput.c_status:
        title: "Design Output Status"
        width: 120
      designVerifications.designVerification.c_status:
        title: "Verification Status"
        width: 120
        multiItem: true    # Required for second linked entity column
    ```

    <Warning title="Non-obvious requirement">
      Omitting `multiItem: true` on the second linked column is one of the most common configuration mistakes during initial setup. The column will either not display data or throw errors without a clear indication of the root cause.
    </Warning>
  </Step>
</Steps>

## Verification

After applying your fixes, reload the Powersheet widget in Polarion and confirm:

* ✅ The custom field column appears with the correct title
* ✅ Existing values from Polarion display in the column
* ✅ You can edit a value, save, and see it persisted when refreshing
* ✅ The field type renders with the appropriate control (text input, date picker, dropdown, checkbox)

Use the **Review Mode** toggle to verify changes before saving. Review mode highlights modified cells and rows, letting you confirm that your custom field edits are tracked correctly before committing them to Polarion.

## See Also

* [Add a Custom Property](/powersheet/guides/data-model/add-custom-property) -- step-by-step guide for adding properties to the data model
* [Add a Column](/powersheet/guides/sheet-configuration/add-column) -- how to define columns in sheet configurations
* [Configure a Formatter](/powersheet/guides/sheet-configuration/configure-formatter) -- customize how field values render
* [Configure Read-Only Column](/powersheet/guides/sheet-configuration/configure-read-only-column) -- control column editability
* [Configure Multi-Item Column](/powersheet/guides/sheet-configuration/configure-multi-item-column) -- set up columns for multi-linked entities
* [Create an Entity Type](/powersheet/guides/data-model/create-entity-type) -- entity type to work item type mapping
* [Handle Validation Errors](/powersheet/guides/save-operations/handle-validation-errors) -- resolve save-time validation issues

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