What causes "createControlledDocMetadata: ops.commit() failed" in hcengineering/platform?

createControlledDocMetadata: ops.commit() failed

Error message

createControlledDocMetadata: ops.commit() failed

What it means

createControlledDocMetadata builds an Ops transaction (adding the document, its mixin metadata, project association, etc.) and commits it. When ops.commit() returns a falsy result, the whole metadata creation failed and nothing was persisted; a warning with the full parameters is logged.

Source

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

  })

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

  const success = await ops.commit()

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

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

export async function createDocumentTemplate (

View on GitHub (pinned to 63e28dc964)

Solutions

Inspect the warning's logged fields (templateId, documentId, space, project, parent, prefix) to find which reference is invalid.
Confirm the template, space, project, and parent all exist before calling createControlledDocMetadata.
Add retry logic around metadata creation for transient conflicts (retryMetadata path).
Check for duplicate codes/prefixes colliding with existing documents in the same project.

Example fix

// before
const r = await createControlledDocMetadata(client, { templateId, documentId, space, project, parent, prefix })
if (!r.success) console.warn('failed', r)
// after
const tpl = await client.findOne(documents.class.DocumentTemplate, { _id: templateId })
if (tpl === undefined) throw new Error('template not found')
const r = await createControlledDocMetadata(client, { templateId, documentId, space, project, parent, prefix })
if (!r.success) throw new Error(`commit failed for document ${documentId}`)

Defensive patterns

Strategy: retry

Validate before calling

const tpl = await client.findOne(documents.class.DocumentTemplate, { _id: templateId })
const proj = await client.findOne(documents.class.Project, { _id: project })
if (tpl === undefined || proj === undefined) throw new Error('template or project missing')

Type guard

function commitSucceeded(r: any): r is { result: true } {
  return r != null && r.result === true
}

Try / catch

const r = await createControlledDocMetadata(client, args)
if (!r.success) {
  console.error('metadata commit failed', args)
  const retry = await retryMetadata(client, args)
  if (!retry.success) throw new Error('metadata creation failed after retry')
}

Prevention

Validate all referenced ids (template, space, project, parent) before building the ops transaction.
Use the built-in retry (retryMetadata) for transient conflicts.
Avoid concurrent creation of the same document id.

When it happens

Trigger: Calling createControlledDocMetadata where one of the ops inside the transaction fails validation or a conflict: duplicate document id, invalid templateId/space/project/parent references, mixin conflict, or the target space/object being deleted mid-commit.

Common situations: Race with another user creating the same document; template deleted after being selected; committing into a space the ops pipeline cannot resolve; sequence/code generation colliding with an existing code.

Related errors

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