hcengineering/platform · error

createDocumentTemplateMetadata: ops.commit() failed

Error message

createDocumentTemplateMetadata: ops.commit() failed

What it means

createDocumentTemplateMetadata creates the metadata record (seqNumber, code, project link) for a document template inside an Ops transaction. When ops.commit() returns falsy result, the metadata was not persisted; the failure is warned with the full parameter set.

Source

Thrown at plugins/controlled-documents/src/docutils.ts:452

  })

  const projectDocumentId = await client.addCollection(
    documents.class.ProjectDocument,
    space,
    projectMetaId,
    documents.class.ProjectMeta,
    'documents',
    {
      project: projectId,
      initial: projectId,
      document: templateId
    }
  )

  const success = await ops.commit()

  if (!success.result) {
    console.warn('createDocumentTemplateMetadata: ops.commit() failed', {
      _class,
      space,
      _mixin,
      project,
      parent,
      templateId,
      prefix,
      specCode,
      specTitle,
      seqNumber,
      code,
      documentMetaId,
      projectDocumentId
    })
  }

  return { success: success.result, seqNumber, code, documentMetaId, projectDocumentId }
}

View on GitHub (pinned to 63e28dc964)

Solutions

1. Use the logged fields (_class, space, _mixin, project, parent, templateId) to find the failing reference.
2. Re-run metadata creation with retry — the callers ({ seqNumber, code, projectDocumentId, success }) already support retry flows.
3. Ensure sequence/code generation is atomic or re-fetch the next sequence on conflict.
4. Verify the template object exists before committing its metadata.

Example fix

// before
const r = await createDocumentTemplateMetadata(client, { templateId, project, parent, space })
if (!r.success) console.warn('meta failed')
// after
let r = await createDocumentTemplateMetadata(client, { templateId, project, parent, space })
if (!r.success) r = await retryMetadata(client, { templateId, project, parent, space })
if (!r.success) throw new Error(`template metadata commit failed: ${templateId}`)

const template = await client.findOne(documents.class.DocumentTemplate, { _id: templateId })
if (template === undefined) throw new Error('template must exist before metadata commit')

function metaCreated(r: any): r is { success: true; seqNumber: number; code: string } {
  return r != null && r.success === true
}

let r = await createDocumentTemplateMetadata(client, args)
if (!r.success) {
  r = await createDocumentTemplateMetadata(client, args) // re-fetch sequence on retry
  if (!r.success) throw new Error('template metadata commit failed')
}

When it happens

Trigger: Calling createDocumentTemplateMetadata where the referenced templateId, project, parent, or space is invalid, the generated code/sequence conflicts with an existing record, or the target template object was deleted between template creation and metadata commit.

Common situations: Sequence number collision under concurrency (two templates metadata created at once); template creation committed but metadata step raced with deletion; wrong project/parent passed from a caller.

Related errors

• createControlledDocMetadata: ops.commit() failed
• createDocumentTemplate: ops.commit() failed
• Employee not found: ${name}
• Author or owner not found: ${header.author} or ${header.owne
• Cannot resolve a document for meta ${meta}

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