hcengineering/platform · error

Update step must have _id and space

Error message

Update step must have _id and space

What it means

An UpdateStep's filled data must carry the _id and space of the document to update, because client.updateDoc(step._class, space, _id, props) requires both. When either is undefined after variable substitution the step is malformed and fails with this error. Like the mixin variant, it indicates a defective or under-specified update step in the init/update script.

Source

Thrown at server/tool/src/initializer.ts:240

    if (step.resultVariable !== undefined) {
      vars[`\${${step.resultVariable}}`] = res
    }
  }

  private async processMixin<T extends Doc>(step: MixinStep<T, T>, vars: Record<string, any>): Promise<void> {
    const data = await this.fillPropsWithMarkdown(step.data, vars, step.markdownFields)
    const { _id, space, ...props } = data
    if (_id === undefined || space === undefined) {
      throw new Error('Mixin step must have _id and space')
    }
    await this.client.createMixin(_id, step._class, space, step.mixin, props)
  }

  private async processUpdate<T extends Doc>(step: UpdateStep<T>, vars: Record<string, any>): Promise<void> {
    const data = await this.fillPropsWithMarkdown(step.data, vars, step.markdownFields)
    const { _id, space, ...props } = data
    if (_id === undefined || space === undefined) {
      throw new Error('Update step must have _id and space')
    }
    await this.client.updateDoc(step._class, space, _id as Ref<Doc>, props)
  }

  private async processBulkUpdate<T extends Doc>(step: BulkUpdateStep<T>, vars: Record<string, any>): Promise<void> {
    const ops = this.client.apply()
    const docs = await this.client.findAll(step._class, { ...(step.query as any) })
    const data = await this.fillPropsWithMarkdown(step.data, vars, step.markdownFields)
    for (const doc of docs) {
      await ops.updateDoc(step._class, doc.space, doc._id, data)
    }
    await ops.commit()
  }

  private async processCreate<T extends Doc>(
    step: CreateStep<T>,
    vars: Record<string, any>,
    defaults: Map<Ref<Class<T>>, Props<T>>

View on GitHub (pinned to 63e28dc964)

Solutions

1. Add the correct _id and space to the update step data.
2. Reference a document found by a previous FindStep via its resultVariable so _id/space are filled at runtime.
3. Validate the script offline (parse all UpdateSteps and assert _id/space presence) before running it against a workspace.

Example fix

// before
await this.client.updateDoc(step._class, space as Ref<Space>, _id as Ref<Doc>, props) // throws when _id/space undefined
// after
if (data._id === undefined) throw new Error(`Update step ${step._id} missing _id`)
await this.client.updateDoc(step._class, data.space as Ref<Space>, data._id as Ref<Doc>, props)

for (const step of script.steps) {
  if (stepIsUpdate(step) && (step.data._id === undefined || step.data.space === undefined)) {
    throw new Error(`UpdateStep missing _id/space: ${JSON.stringify(step).slice(0, 120)}`)
  }
}

function isUpdatable<T extends Doc>(d: Partial<T> | undefined): d is T & { _id: Ref<T>, space: Ref<Space> } {
  return d !== undefined && d._id !== undefined && (d as any).space !== undefined
}

try {
  await this.client.updateDoc(step._class, space, _id as Ref<Doc>, props)
} catch (err) {
  if ((err as Error).message === 'Update step must have _id and space') {
    console.error('UpdateStep data must include _id and space; check variable bindings', step)
  }
  throw err
}

When it happens

Trigger: An UpdateStep whose data lacks _id or space after fillPropsWithMarkdown — omitted fields, or ${var} placeholders that resolved to undefined because no earlier step bound them.

Common situations: Scripts copied from examples with placeholder _id/space never replaced; dependent variables not defined by a preceding FindStep; bulk-generated scripts where some steps lost required identity fields.

Related errors

• Mixin step must have _id and space
• Failed to load server config
• getDisplayMedia not supported
• No screen access granted
• 'from' is missing

AI-assisted analysis of hcengineering/platform@63e28dc964 (2026-08-29). Data as JSON: /api/errors/330a547fdfa47e97. Report an issue: GitHub.