What causes "File not found: ${fileAbsPath}" in hcengineering/platform?

Verify the exact absolute path in the message exists (ls the path) and create/restore the file if missing.

File not found: ${fileAbsPath}

Error message

File not found: ${fileAbsPath}

What it means

validateFileExists is a precondition helper that throws when an absolute file path passed to the processor does not exist on disk. It ensures referenced source files are present before any parsing is attempted, giving a clear early failure instead of downstream read errors.

Source

Thrown at packages/importer/src/huly/cards.ts:898

  private validateFormat (data: Record<string, any>, schema: FormatSchema, filePath: string): void {
    const currentPath = path.dirname(filePath)
    const errors = validateSchema(data, schema, currentPath)
    if (errors.length > 0) {
      throw new Error(
        'Invalid import schema in ' +
          filePath +
          ': \n' +
          Array.from(errors)
            .map((e) => `    * ${e}`)
            .join(';\n') +
          '\n'
      )
    }
  }

  private validateFileExists (fileAbsPath: string): void {
    if (!fs.existsSync(fileAbsPath)) {
      throw new Error('File not found: ' + fileAbsPath)
    }
  }
}

View on GitHub (pinned to 63e28dc964)

Solutions

Verify the exact absolute path in the message exists (ls the path) and create/restore the file if missing.
Fix casing to match the filesystem exactly (Linux is case-sensitive).
Check how the path is constructed — ensure relative references resolve from the correct base directory.
Ensure the file is committed/pulled and not excluded by .gitignore, LFS settings, or CI checkout rules.

Example fix

// before
await processor.process('docs/Cards/Note.md') // wrong casing, file is cards/note.md
// after
await processor.process(path.resolve('docs/cards/note.md'))

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'fs'
import path from 'path'
function assertFileExists(file: string): string {
  const abs = path.resolve(file)
  if (!fs.existsSync(abs)) throw new Error(`Pre-check failed: ${abs} does not exist`)
  return abs
}

Try / catch

try {
  await processor.process(file)
} catch (e) {
  if (e instanceof Error && e.message.startsWith('File not found:')) {
    const p = e.message.replace('File not found: ', '')
    console.error(`${p} missing — check existence, casing, and that the file isn't gitignored/LFS-skipped`)
  } else throw e
}

Prevention

Always resolve paths to absolute before passing them to the processor.
On Linux, match file-name casing exactly.
Ensure referenced files are committed and not excluded by .gitignore, LFS, or CI checkout rules.
Run an existence pre-check over all input paths before starting a bulk import.

When it happens

Trigger: Calling a CardsProcessor entry point with a file path (card, blob, or referenced document) that has been deleted, renamed, or whose path was constructed incorrectly (wrong relative base, wrong casing, missing volume/working directory).

Common situations: Files excluded by .gitignore or LFS not checked out; case-sensitive filesystems where the path casing differs; running the importer from a different working directory so relative-to-cwd paths resolve elsewhere; stale cached paths after a refactor.

Related errors

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