Couldn't find the parent project document object with id: ${

Error message

Couldn't find the parent project document object with id: ${parent}

What it means

getParentPath in controlled-documents resolves the breadcrumb/path of parent DocumentMeta objects for a parent ProjectDocument. If client.findOne on documents.class.ProjectDocument finds no object for the given parent Ref, it warns "Couldn't find the parent project document object with id: <parent>" and returns []. Callers (createControlledDocMetadata, createDocumentTemplateMetadata, createNewFolder) then proceed with an empty path, producing documents with missing/incorrect hierarchy metadata.

Source

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

  type DocumentSpace,
  type DocumentTemplate,
  type HierarchyDocument,
  type Project,
  type ProjectDocument,
  DocumentState
} from './types'
import { makeRank } from '@hcengineering/rank'

import documents from './plugin'
import { getDocumentId, getFirstRank, TEMPLATE_PREFIX } from './utils'

async function getParentPath (client: TxOperations, parent: Ref<ProjectDocument>): Promise<Array<Ref<DocumentMeta>>> {
  const parentDocObj = await client.findOne(documents.class.ProjectDocument, {
    _id: parent
  })

  if (parentDocObj === undefined) {
    console.warn(`Couldn't find the parent project document object with id: ${parent}`)
    return []
  }

  const parentMeta = await client.findOne(documents.class.ProjectMeta, {
    _id: parentDocObj.attachedTo
  })

  if (parentMeta === undefined) {
    console.warn(`Couldn't find the parent document meta with id: ${parentDocObj.attachedTo}`)
    return []
  }

  return [parentMeta.meta, ...parentMeta.path]
}

export async function createControlledDocFromTemplate (
  client: TxOperations,
  templateId: Ref<DocumentTemplate> | undefined,

View on GitHub (pinned to 63e28dc964)

Solutions

Verify the parent Ref is valid and the ProjectDocument exists (query it in the same client/workspace) before calling createNewFolder/createControlledDocMetadata.
Create the parent document first and use its returned _id as parent.
Check for deletions: ensure the parent was not removed between obtaining the Ref and the call.
Confirm you are connected to the correct workspace - findOne silently misses objects outside it.

Example fix

// before
await createNewFolder(client, someParentRef, name) // someParentRef may be stale
// after
const parent = await client.findOne(documents.class.ProjectDocument, { _id: someParentRef })
if (parent === undefined) throw new Error(`Parent ${someParentRef} not found`) // fail fast instead of empty path
await createNewFolder(client, someParentRef, name)

Defensive patterns

Strategy: validation

Validate before calling

// Verify the parent exists before building metadata/folders
const parentDoc = await client.findOne(documents.class.ProjectDocument, { _id: parent })
if (parentDoc === undefined) {
  throw new Error(`Parent project document ${parent} does not exist in this workspace`)
}

Type guard

function isRef<T extends Doc> (value: unknown): value is Ref<T> {
  return typeof value === 'string' && value.length > 0
}

Try / catch

try {
  const path = await getParentPath(client, parent)
  if (path.length === 0) throw new Error('Parent path empty - parent not found')
} catch (err) {
  console.error('Cannot resolve parent hierarchy', err)
}

Prevention

Create parent documents before children and use returned _ids.
Never hardcode or copy Refs across workspaces/tests.
Handle deletions of parents that would orphan child creation.
Confirm the client is bound to the correct workspace before lookups.

When it happens

Trigger: Called with a parent Ref pointing to a ProjectDocument that does not exist in the DB - stale/deleted reference, wrong Ref passed, wrong workspace/connection, or the parent was not yet created when the caller ran.

Common situations: Passing an ID from another workspace or a removed project document; race where a folder/document is created before its parent commit is visible; copy-pasted or hardcoded Refs in tests/scripts; parent deleted after child creation started.

Related errors

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