stablyai/orca · error · LinearWriteFailure

failed

failed

Error message

Linear relation creation failed

What it means

Thrown by createLinearIssueRelation when the GraphQL issueRelationCreate response lacks success===true or lacks the created issueRelation node. The mutation reached Linear and came back, but Linear reported failure (or returned an unexpected shape). Encoded as LinearWriteFailure kind 'failed'.

Solutions

1. Verify issueId and relatedIssueId are valid, existing Linear issue ids.
2. Confirm the relation type is one Linear accepts for that issue pair.
3. Ensure the API token has write permission on both issues.
4. Inspect raw.data?.issueRelationCreate for Linear's error detail; fall back to the Linear web UI if the SDK hides it.

Example fix

// before
await createLinearIssueRelation(client, { issueId, relatedIssueId, type: 'BLOCKS' })
// after
const validTypes = ['blocks','isBlockedBy','duplicate','relatesTo']
if (!validTypes.includes(type)) throw new Error('bad type')
await createLinearIssueRelation(client, { issueId, relatedIssueId, type })

const validTypes = ['blocks','isBlockedBy','duplicate','relatesTo']
if (!validTypes.includes(input.type) || !input.issueId || !input.relatedIssueId) throw new Error('invalid relation input')

function isLinearWriteFailure(e: unknown): e is LinearWriteFailure {
  return e instanceof Error && (e as LinearWriteFailure).name === 'LinearWriteFailure'
}

try { return await createLinearIssueRelation(client, input) }
catch (e) {
  if (e instanceof LinearWriteFailure && e.kind === 'failed') { await refreshRelations(input.issueId); throw e }
  throw e
}

When it happens

Trigger: Linear rejects the relation input — invalid issueId/relatedIssueId, an unsupported relation type, a cyclic/disallowed relation, or a permission error returned as success:false. Also when the schema changes and issueRelationCreate no longer returns the expected node fields.

Common situations: User links two issues across teams/permission boundaries. Relation type string is wrong (case-sensitive). Issue was deleted between selection and create. API token lacks write scope for relations.

Related errors

• failed
• unconfirmed
• Concrete Linear workspace ID is required
• Concrete Linear workspace ID is required
• Custom view ID is required

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/778279e047101244. Report an issue: GitHub.

Appendix: source

Thrown at src/main/linear/issue-relation-mutation.ts:46

const DELETE_RELATION_MUTATION = `
  mutation OrcaLinearDeleteIssueRelation($id: String!) {
    issueRelationDelete(id: $id) { success }
  }
`

export async function createLinearIssueRelation(
  client: LinearClient,
  input: { issueId: string; relatedIssueId: string; type: string }
): Promise<RawRelationNode> {
  const raw = await runRelationMutation(() =>
    client.client.rawRequest<RelationMutationResponse, Record<string, unknown>>(
      CREATE_RELATION_MUTATION,
      { input }
    )
  )
  const created = raw.data?.issueRelationCreate
  if (created?.success !== true || !created.issueRelation) {
    throw new LinearWriteFailure('failed', 'Linear relation creation failed')
  }
  return created.issueRelation
}

export async function deleteLinearIssueRelation(
  client: LinearClient,
  relationId: string
): Promise<void> {
  const raw = await runRelationMutation(() =>
    client.client.rawRequest<RelationMutationResponse, Record<string, unknown>>(
      DELETE_RELATION_MUTATION,
      { id: relationId }
    )
  )
  if (raw.data?.issueRelationDelete?.success !== true) {
    throw new LinearWriteFailure('failed', 'Linear relation removal failed')
  }
}

View on GitHub (pinned to 1136503c6a)