hcengineering/platform · error

Document not found: ${JSON.stringify(query)}

Error message

Document not found: ${JSON.stringify(query)}

What it means

The initializer's processFind step resolves a FindStep by running findOne against the target client; findOne returning undefined means no document matched the (variable-filled) query. The step cannot continue because later steps may reference the found document via its result variable, so the initializer fails fast. This is a data/precondition mismatch: the script expects a document that does not exist in this workspace.

Source

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

  }

  private async processImport (step: ImportStep, vars: Record<string, any>, logger: ModelLogger): Promise<void> {
    try {
      const uploader = new StorageFileUploader(this.ctx, this.storageAdapter, this.wsIds)
      const initPath = path.resolve(this.initRepoDir, step.path)
      const importer = new HulyFormatImporter(this.client, uploader, logger, vars)
      await importer.importFolder(initPath)
    } catch (error) {
      logger.error('Import failed', error)
      throw error
    }
  }

  private async processFind<T extends Doc>(step: FindStep<T>, vars: Record<string, any>): Promise<void> {
    const query = this.fillProps(step.query, vars)
    const res = await this.client.findOne(step._class, { ...(query as any) })
    if (res === undefined) {
      throw new Error(`Document not found: ${JSON.stringify(query)}`)
    }
    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

View on GitHub (pinned to 63e28dc964)

Solutions

1. Verify the document exists with a matching query (check _id, space, _class, and filter fields) in the target workspace.
2. Fix the FindStep query in the script, or add a preceding Create/Update step ensuring the document exists before find.
3. Make the step tolerant: check res === undefined and skip or create the document instead of failing when the find is optional.

Example fix

// before
const res = await this.client.findOne(step._class, { ...(query as any) })
if (res === undefined) throw new Error(`Document not found: ${JSON.stringify(query)}`)
// after
const res = await this.client.findOne(step._class, { ...(query as any) })
if (res === undefined) return // optional find: nothing to bind to resultVariable

const existing = await client.findOne(step._class, step.query as any)
if (existing === undefined) {
  console.error(`FindStep will fail: no ${step._class} matching`, step.query)
}

function isFound<T extends Doc>(doc: T | undefined): doc is T {
  return doc !== undefined
}

try {
  await initializer.processScript(ctx, script)
} catch (err) {
  if ((err as Error).message.startsWith('Document not found:')) {
    console.error('Fix the FindStep query or ensure the document is created first:', err.message)
  }
  throw err
}

When it happens

Trigger: Running an init/update script whose FindStep query matches nothing: the document was renamed, deleted, was created by a previous skipped step, or the query has wrong values after fillProps variable substitution.

Common situations: Re-running init scripts on a workspace where the target document's _id/space differs; script written against demo/seed data that is absent; typo in query fields or a _class mismatch; version upgrade where the referenced object no longer exists.

Related errors

• Hierarchy is not defined
• Model is not defined
• Agent server already running at ${endpointUrl}
• Agent endpoint not initialized after server start
• Low level storage is not available

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