{"record":{"id":"5f34bf1f50c168db","repo":"hcengineering/platform","slug":"createcontrolleddocmetadata-ops-commit-failed","errorCode":null,"errorMessage":"createControlledDocMetadata: ops.commit() failed","messagePattern":"createControlledDocMetadata: ops\\.commit\\(\\) failed","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"plugins/controlled-documents/src/docutils.ts","lineNumber":270,"sourceCode":"  })\n\n  const projectDocumentId = await client.addCollection(\n    documents.class.ProjectDocument,\n    space,\n    projectMetaId,\n    documents.class.ProjectMeta,\n    'documents',\n    {\n      project: projectId,\n      initial: projectId,\n      document: documentId\n    }\n  )\n\n  const success = await ops.commit()\n\n  if (!success.result) {\n    console.warn('createControlledDocMetadata: ops.commit() failed', {\n      templateId,\n      documentId,\n      space,\n      project,\n      parent,\n      prefix,\n      seqNumber,\n      specCode,\n      specTitle,\n      documentMetaId,\n      projectDocumentId\n    })\n  }\n\n  return { success: success.result, seqNumber, documentMetaId, projectDocumentId }\n}\n\nexport async function createDocumentTemplate (","sourceCodeStart":252,"sourceCodeEnd":288,"githubUrl":"https://github.com/hcengineering/platform/blob/63e28dc96483967b2fc21c881b3f1023c1de7718/plugins/controlled-documents/src/docutils.ts#L252-L288","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nconst r = await createControlledDocMetadata(client, { templateId, documentId, space, project, parent, prefix })\nif (!r.success) console.warn('failed', r)\n// after\nconst tpl = await client.findOne(documents.class.DocumentTemplate, { _id: templateId })\nif (tpl === undefined) throw new Error('template not found')\nconst r = await createControlledDocMetadata(client, { templateId, documentId, space, project, parent, prefix })\nif (!r.success) throw new Error(`commit failed for document ${documentId}`)","handlingStrategy":"retry","validationCode":"const tpl = await client.findOne(documents.class.DocumentTemplate, { _id: templateId })\nconst proj = await client.findOne(documents.class.Project, { _id: project })\nif (tpl === undefined || proj === undefined) throw new Error('template or project missing')","typeGuard":"function commitSucceeded(r: any): r is { result: true } {\n  return r != null && r.result === true\n}","tryCatchPattern":"const r = await createControlledDocMetadata(client, args)\nif (!r.success) {\n  console.error('metadata commit failed', args)\n  const retry = await retryMetadata(client, args)\n  if (!retry.success) throw new Error('metadata creation failed after retry')\n}","preventionTips":["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."],"tags":["controlled-documents","commit-failure","transaction"],"backgroundTag":"transaction-commit-failed","analyzedSha":"63e28dc96483967b2fc21c881b3f1023c1de7718","analyzedAt":"2026-08-29T15:21:27.377Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}