# diagnose_sync

Behavior, inputs, outputs and permissions for diagnose_sync.

Source: https://docs.getridian.com/developers/tools/diagnose_sync/
Language: en
Reviewed: 2026-10-06

This reference is generated from the published tool contract.

## Behavior and boundaries

Explains why one of the user's own sync pairs is not running, using the recorded state and reason, and names the calendars involved where the granted selection covers them. Reasons are a closed set; an unrecognised one is reported as `other` rather than guessed, and then no next step is claimed. It reports no event-level causes. Reconnecting an account, reviewing the workspace's plan details or changing the target of an existing pair happens in the Ridian app; nextStepUrl links to the page for the recorded next step.

## Permissions

Granted scopes, accounts, calendars and visibility rules limit access. Workspace administrators do not automatically gain access to other users’ accounts.

`sync:read`

[Consent and boundaries](https://docs.getridian.com/developers/authentication/)

## Input

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40
    }
  },
  "required": [
    "ref"
  ],
  "additionalProperties": false
}
```

## Output

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "syncs": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "ref": {
            "type": "string"
          },
          "source": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "name"
            ],
            "additionalProperties": false
          },
          "target": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "id",
              "name"
            ],
            "additionalProperties": false
          },
          "twoWay": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "paused",
              "error",
              "deleting"
            ]
          },
          "reason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "userPaused",
                  "sourceUnavailable",
                  "targetUnavailable",
                  "targetReadOnly",
                  "unsupportedProvider",
                  "planLimit",
                  "other"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "nextStep": {
            "type": [
              "string",
              "null"
            ]
          },
          "nextStepUrl": {
            "type": [
              "string",
              "null"
            ]
          },
          "unavailableSince": {
            "type": [
              "number",
              "null"
            ]
          }
        },
        "required": [
          "ref",
          "source",
          "target",
          "twoWay",
          "status",
          "reason",
          "nextStep",
          "nextStepUrl",
          "unavailableSince"
        ],
        "additionalProperties": false
      }
    },
    "scope": {
      "type": "string",
      "const": "own_pairs_in_this_workspace"
    }
  },
  "required": [
    "syncs",
    "scope"
  ],
  "additionalProperties": false
}
```

## Errors and retries

Check the tool result for errors. Do not blindly retry writes after a timeout. Check the current resource or send status first.

[Error handling](https://docs.getridian.com/developers/errors/)