hcengineering/platform · error · Error

Failed to create document template attached doc: ${template.

Error message

Failed to create document template attached doc: ${template.title}

What it means

createDocTemplateAttachedDoc builds a transaction batch (ops.addCollection + ops.createMixin) and commits it. If commit() returns a result without result set, the transaction failed server-side and the attached ControlledDocument for the template was not created, so the importer throws this error.

Source

Thrown at packages/importer/src/importer/importer.ts:1241

        seqNumber,
        prefix: template.docPrefix,
        content: contentId,
        changeControl: changeControlId,
        commentSequence: 0,
        requests: 0,
        labels: 0
      },
      template.id as unknown as Ref<ControlledDocument>
    )

    await ops.createMixin(template.id, documents.class.Document, spaceId, documents.mixin.DocumentTemplate, {
      sequence: 0,
      docPrefix: template.docPrefix
    })

    const commit = await ops.commit()
    if (!commit.result) {
      throw new Error('Failed to create document template attached doc: ' + template.title)
    }

    this.logger.log('Document template attached doc created: ' + result)
    return result
  }

  private async createControlledDocMetaHierarhy (
    doc: ImportControlledDocument,
    templateMetaMap: Map<Ref<ControlledDocument>, { seqNumber: number, code: string }>,
    spaceId: Ref<DocumentSpace>,
    parentProjectDocumentId?: Ref<ProjectDocument>
  ): Promise<Ref<ControlledDocument>> {
    this.logger.log('Creating controlled document: ' + doc.title)
    const documentId = doc.id ?? generateId<ControlledDocument>()

    const result = await createControlledDocMetadata(
      this.client,
      documents.template.ProductChangeControl,

View on GitHub (pinned to 63e28dc964)

Solutions

Inspect commit() result/error details and server logs to find which tx in the batch was rejected.
Verify template.metaId (parent DocumentMeta) and spaceId still exist and are writable before committing.
Ensure the importing account has permission to add ControlledDocument and the DocumentTemplate mixin in the space.
Retry the import; if transient conflicts, serialize imports or retry the commit with backoff.
Align importer/server versions so the ControlledDocument data schema matches what addCollection sends.

Example fix

// before
const commit = await ops.commit()
if (!commit.result) {
  throw new Error('Failed to create document template attached doc: ' + template.title)
}
// after
const commit = await ops.commit()
if (!commit.result) {
  this.logger.error('Commit failed for template attached doc', { title: template.title, commit })
  throw new Error('Failed to create document template attached doc: ' + template.title)
}

Defensive patterns

Strategy: retry

Validate before calling

const spaceDoc = await client.findOne(documents.class.OrgSpace, { _id: spaceId })
if (spaceDoc === undefined) throw new Error('Target space missing before import')
const meta = template.metaId !== undefined
  ? await client.findOne(documents.class.DocumentMeta, { _id: template.metaId })
  : undefined
if (template.metaId !== undefined && meta === undefined) throw new Error('Parent DocumentMeta missing: ' + template.metaId)

Type guard

function isCommitSuccess(commit: { result?: unknown }): commit is { result: NonNullable<unknown> } {
  return commit.result !== undefined && commit.result !== null
}

Try / catch

try {
  await importer.importOrgSpace(space)
} catch (err) {
  if (err instanceof Error && err.message.startsWith('Failed to create document template attached doc:')) {
    await delay(backoff)
    await importer.importOrgSpace(space) // retry after checking server state
  } else throw err
}

Prevention

Verify the parent DocumentMeta and space exist and are writable before the commit
Run imports serially to avoid concurrent-modification commit conflicts
Add retry with backoff for transient commit failures
Check server tx-rejection logs after any failed import and align schemas/versions

When it happens

Trigger: ops.commit() returns { result: undefined } while creating the template's attached ControlledDocument — e.g. a tx in the batch is rejected (invalid parent metaId, missing space, permission denial), or a concurrent modification/ conflicts during commit.

Common situations: Target space or template.metaId document missing/deleted before the commit; account lacking create permission for ControlledDocument in the space; server-side tx validation failures after schema changes; transient connectivity drop during commit.

Related errors

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