Skip to main content

​
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

​
Step 1: Verify the Model Path in Sheet Configuration

The sources.model property in your sheet configuration must match the name of your domain model file. Open your sheet configuration YAML and check the sources section: 
sources:
  - model: my-custom-model    # Must match your model file name
    from: UserNeed
    expand:
      - systemRequirements.systemRequirement
The sources.model property must match your custom domain 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.

​
Step 2: Check the Model Path Resolution

Powersheet resolves model paths using these rules:
Model ValueResolved Path
my-model{projectId}/my-model (current project)
otherProject/my-modelotherProject/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 > Domain Models.

​
Step 3: Verify Connection Status

Connections go through three lifecycle states: diagram
  • 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 domain model configuration contains an error that prevented initialization.

​
Step 4: Validate the Domain Model YAML

Common domain 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
# Correct structure
domainModelTypes:
  UserNeed:
    polarionType: requirement
    properties:
      description: ~
      severity: ~
When you save a connection configuration, Powersheet automatically restarts the connection to apply changes. Check the updated status after saving to confirm the fix.

​
Step 5: 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 domain model
sources:
  - model: my-custom-model
    from: UserNeed              # Must be a domainModelTypes key
    expand:
      - systemRequirements.systemRequirement
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.

​
Verification

After applying your fix:
  1. Save the domain 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

Sources: admin.cy.ts, create-document-connection-and-change-status.spec.ts, ConfigProvider.tsx, model-helper.md
KB ArticlesSupport TicketsSource Code
  • prod-powersheet-src/com.nextedy.powersheet.client/ltc-repo/cypress/e2e/Admin/create-document-connection-and-change-status.spec.ts
  • prod-powersheet-src/com.nextedy.powersheet.client/cypress/e2e/admin/admin.cy.ts
  • ServerRenderer.java
  • HttpErrorInfo.java
  • build.properties