yamadashy/repomix · error · RepomixError

Instruction file not found at ${instructionPath}

Error message

Instruction file not found at ${instructionPath}

What it means

Repomix throws this when `config.output.instructionFilePath` is set but the file at that path (resolved against `config.cwd`) cannot be read — typically because it does not exist, though any read failure (permission, directory, bad encoding) hits the same catch. It wraps the silent fs failure into a user-facing RepomixError so CLI runs fail fast with a clear message instead of silently producing output without the custom instructions.

Source

Thrown at src/core/output/outputGenerate.ts:334

  processedFiles: ProcessedFile[],
  gitDiffResult: GitDiffResult | undefined = undefined,
  gitLogResult: GitLogResult | undefined = undefined,
  filePathsByRoot?: FilesByRoot[],
  emptyDirPaths?: string[],
  deps = {
    listDirectories,
    listFiles,
    searchFiles,
  },
): Promise<OutputGeneratorContext> => {
  let repositoryInstruction = '';

  if (config.output.instructionFilePath) {
    const instructionPath = path.resolve(config.cwd, config.output.instructionFilePath);
    try {
      repositoryInstruction = await fs.readFile(instructionPath, 'utf-8');
    } catch {
      throw new RepomixError(`Instruction file not found at ${instructionPath}`);
    }
  }

  // Determine if full-tree mode applies (only when directory structure is rendered)
  const shouldUseFullTree =
    config.output.directoryStructure === true &&
    !!config.output.includeFullDirectoryStructure &&
    (config.include?.length ?? 0) > 0;

  // Paths to include in the directory tree visualization
  let directoryPathsForTree: string[] = [];
  let filePathsForTree: string[] = allFilePaths;

  // Only prefix with the per-root label for genuine multi-root packs. For a single
  // root, filePathsByRoot still carries a basename fallback label, but pack() leaves
  // single-root file paths unprefixed — so prefixing the full-tree directories here
  // would desync them from the included files and add a spurious root branch.
  const toOutputDisplayPath = (rootDir: string, filePath: string, index: number): string =>

View on GitHub (pinned to f465ad9093)

Solutions

1. Verify the file exists at path.resolve(config.cwd, config.output.instructionFilePath) and create it if missing.
2. Fix the path in config (use an absolute path or one correct relative to the cwd repomix runs in).
3. Remove `output.instructionFilePath` from the config if custom instructions are not needed.
4. Check file read permissions if the file exists but is unreadable.

Example fix

// before (repomix.json, run from repo root but file lives in docs/)
"instructionFilePath": "custom-instructions.md"
// after
"instructionFilePath": "docs/custom-instructions.md"

import fs from 'node:fs/promises';
import path from 'node:path';
const p = path.resolve(config.cwd, config.output.instructionFilePath);
await fs.access(p, fs.constants.R_OK); // throws ENOENT before repomix runs

null

try {
  await pack(...);
} catch (e) {
  if (e instanceof RepomixError && e.message.startsWith('Instruction file not found')) {
    console.error(`Check output.instructionFilePath (cwd=${config.cwd})`);
  } else throw e;
}

When it happens

Trigger: Calling repomix pack (or the API's output generation, via outputGeneratorContext -> buildOutputGeneratorContext) with `output.instructionFilePath` pointing to a path that does not exist relative to `config.cwd`, or to an unreadable file.

Common situations: A relative path in repomix.json that resolves differently because cwd differs (e.g. running from a subdirectory or CI workspace root); a renamed/deleted custom-instructions.md; committing a config referencing a file gitignored on CI; typos like `intructions.md`.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• In remote mode, --config must be an absolute path to avoid l
• Config file not found at ${argConfigPath}
• Unsupported config file format: ${filePath}
• Unsupported output style for handlebars template: ${style}
• Failed to generate XML output: ${error instanceof Error ? er

AI-assisted analysis of yamadashy/repomix@f465ad9093 (2026-08-29). Data as JSON: /api/errors/d1b0ee1f5bd91a09. Report an issue: GitHub.