Troubleshooting

Start from the observed effect

Useful diagnostics identify the object, operation, reason and possible action. They retain business language in the interface and expose technical detail when needed.

If a Surface cannot be opened, try opening it again from its Workspace. An unavailable message does not establish that access was revoked or that a previous operation failed. When the requested version has changed, reopen the current version before continuing; do not repeat an accepted Action to resolve a reading problem.

For a save, distinguish preparing the input, an unknown response and a version already saved. If input cannot be retained for another view, keep the editor open and try again before leaving or reloading. If the response is missing, resume the same pending request. If the version is saved but its display cannot be refreshed, reopen the Surface without repeating the save.

A conflict requires reviewing your draft and the current version; Surface does not merge them automatically. Changing the interface language does not repeat the save or replace your input.

Distinguish an unavailable connection to the host app, a host that does not support Surface context, and context synchronization that was not confirmed. An unconfirmed synchronization does not establish that AI received the context. If a context retry is offered, request it explicitly; it does not repeat a save or another Action, or automatically reconnect the host.

If live updates are interrupted, use Reconnect when offered. Refresh resumes a read deferred while you finish editing or resolve a pending save. These gestures reread the current authorized work; they do not repeat a save or Action, confirm an uncertain operation, or prove that access was revoked. Keep your draft and resolve any version conflict before replacing the displayed content.

Symptom	Check	Useful next step
Missing Field	Surface/Settings placement and definition	Correct Model presentation
Cannot create	Required values and Form	Display or supply missing information
Client not found	Link target, search and access	Check integration and permissions
Incomplete table	Query, filters and pagination	Inspect effective scope
Unavailable Action	Conditions, capability and permissions	Correct the stated cause
Waiting Flow	Step, decision or connection	Open the next action
Unexpected AI proposal	Sources, version and profile	Inspect context used
Conflicting remote change	Draft and current version	Compare before applying

Example

North Studio does not appear in a quote’s client selector. First check the target Clients Workspace, record type and member permissions. Do not create a duplicate client to work around an incorrect target or reading refusal.

Prepare a support request

If a chat result cannot be displayed, reopen Surface to consult the current content or operation state. This display refusal does not tell you whether the operation was accepted, rejected or cancelled. When its outcome is uncertain, resume the same pending operation rather than submitting a new one.

For an oversized or overly complex AI tool call, check the MCP request limits. Keep the reported refusal distinct from a lost response; increasing your plan does not remove a technical request limit.

Retain operation identity, context and the useful message. Exclude secrets, keys and unnecessary private information. State expected and observed behavior. A screenshot does not replace operation state when the response is uncertain.

Verify recovery

After correction, resume the affected operation and inspect the result. Use validation and preview for Model changes; inspect the receipt before retrying accepted operations. Retries explains how to avoid repeated effects.

Applied examples : Find the cause of a blocker

First check the required Field, then the reference supplied to the client Query.

Configuration

Fragment placed in rules[]. Properties and accepted values.

{
  "contract": "WorkspaceRule@1",
  "key": "company-required",
  "label": "Company provided",
  "expression": {
    "kind": "present",
    "field": {
      "definitionPath": "workspace/clients/surface/client",
      "fieldKey": "company"
    }
  }
}

Variation and connection

Fragment placed in presentation.recordProfiles[].queryBindings[]. Properties and accepted values.

{
  "key": "client-quotes",
  "queryKey": "client-quotes",
  "parameters": {
    "clientId": {
      "kind": "entity-id",
      "definitionPath": "workspace/clients/surface/client"
    }
  }
}

UI layout example

The illustrative layout below places this configuration in the Clients/Quotes app. Insert each fragment at the stated location, with Field, Query and Action references matching the Model declarations.

1. Target object
2. Proposed change
3. Checks
4. Confirm

SurfaceClients / North StudioExample

TroubleshootingFind the cause of a blocker

Clients

NS

North StudioQuote S-1042

Needs review

Proposed change

First check the required Field, then the reference supplied to the client Query.

Data and references

Client · Need · Pricing

BackReview then confirm