What causes "Cannot resolve a document for meta ${meta}" in hcengineering/platform?

Ensure a non-archived ProjectDocument exists and is linked to the meta's document chain

Cannot resolve a document for meta ${meta}

Error message

Cannot resolve a document for meta ${meta}

What it means

getDocumentMetaLinkFragment walks the revision history of a controlled document's meta to find a target document, and throws if none can be resolved. This means the meta document exists but no associated ProjectDocument in a resolvable state (not archived/terminated) could be found. It guards link generation from producing broken locations.

Source

Thrown at plugins/controlled-documents-resources/src/utils.ts:181

  let targetDocument: ControlledDocument | undefined
  for (const doc of docs) {
    if (doc.state === DocumentState.Effective) {
      targetDocument = doc
      break
    } else if (doc.state === DocumentState.Deleted && targetDocument === undefined) {
      targetDocument = doc
    } else if (doc.state === DocumentState.Obsolete && targetDocument === undefined) {
      targetDocument = doc
    } else if (doc.state === DocumentState.Draft) {
      targetDocument = doc
    } else if (doc.state === DocumentState.Archived) {
      break
    }
  }

  if (targetDocument === undefined) {
    throw new Error('Cannot resolve a document for meta ' + meta)
  }

  const projectDoc = await client.findOne(
    documents.class.ProjectDocument,
    { document: targetDocument._id },
    {
      lookup: {
        project: documents.class.Project
      },
      sort: {
        '$lookup.project.createdOn': SortingOrder.Descending
      },
      limit: 1
    }
  )

  const project = projectDoc?.project ?? documents.ids.NoProject

View on GitHub (pinned to 63e28dc964)

Solutions

Ensure a non-archived ProjectDocument exists and is linked to the meta's document chain
Restore/re-create the ProjectDocument if it was wrongly archived or deleted
Skip link generation for archived/terminated documents instead of resolving a fragment
Clean up orphaned meta records so links are only generated for valid documents

Defensive patterns

Strategy: try-catch

Validate before calling

const target = await walkDocumentChain(client, meta) // equivalent traversal
if (target === undefined) return undefined // skip link generation

Try / catch

try {
  return await getDocumentMetaLinkFragment(meta)
} catch (err) {
  if (err.message.startsWith('Cannot resolve a document for meta')) {
    return undefined // render no link for archived/orphaned meta
  }
  throw err
}

Prevention

Skip link generation for archived/terminated documents
Clean up orphaned meta records during deletions
Verify the document chain before generating link fragments
Keep ProjectDocument links intact during migrations

When it happens

Trigger: Generating a link fragment for a ControlledDocumentMeta whose document chain only contains Archived documents or has no documents at all; orphaned meta records after deletions.

Common situations: Linking to a controlled document whose project document was archived; stale meta records left after data cleanup; importing meta data without corresponding ProjectDocuments.

Related errors

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