Yeachan-Heo/oh-my-codex · error · Error

launch instructions file not found: ${appendixPath}

Error message

launch instructions file not found: ${appendixPath}

What it means

A configured launch-instructions appendix file (an extra prompt/instructions file to append at launch) was specified but does not exist on disk. The builder refuses to silently skip it, so it throws with the offending path.

Source

Thrown at src/cli/index.ts:5520

            args: ["set-option", "-t", sessionName, OMX_INSTANCE_OPTION, sessionId],
          },
        ]
      : []),
    { name: "split-and-capture-hud-pane", args: splitCaptureArgs },
  ];
}

async function readLaunchAppendInstructions(): Promise<string> {
  const appendixCandidates = [
    process.env[OMX_RALPH_APPEND_INSTRUCTIONS_FILE_ENV]?.trim(),
    process.env[OMX_AUTORESEARCH_APPEND_INSTRUCTIONS_FILE_ENV]?.trim(),
  ].filter(
    (value): value is string => typeof value === "string" && value.length > 0,
  );
  if (appendixCandidates.length === 0) return "";
  const appendixPath = appendixCandidates[0];
  if (!existsSync(appendixPath)) {
    throw new Error(`launch instructions file not found: ${appendixPath}`);
  }
  const { readFile } = await import("fs/promises");
  return (await readFile(appendixPath, "utf-8")).trim();
}

export function shouldAttachDetachedTmuxSession(
  env: NodeJS.ProcessEnv = process.env,
): boolean {
  return env.OMX_HERMES_MCP_BRIDGE !== "1";
}

function stripHermesMcpBridgeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
  const { OMX_HERMES_MCP_BRIDGE: _bridge, ...rest } = env;
  return rest;
}

export function buildDetachedSessionFinalizeSteps(
  sessionName: string,

View on GitHub (pinned to 3ad79a8a6f)

Solutions

1. Check the path in the error message and create or restore the file
2. If the path is relative, run from the project root or change the config to an absolute/repo-relative path that resolves from the launch cwd
3. Remove the appendix setting from config if the file is no longer needed
4. If it should be per-machine, template the config (e.g. gitignore a local override)

Example fix

// before
instructionsAppendix: "./AGENTS_APPENDIX.local.md" // missing on this machine

// after
instructionsAppendix: existsSync("./AGENTS_APPENDIX.local.md") ? "./AGENTS_APPENDIX.local.md" : undefined

import { existsSync } from "node:fs";
const appendix = config.instructionsAppendix;
if (appendix && !existsSync(resolve(cwd, appendix))) config.instructionsAppendix = undefined;

try { await launch(cfg); } catch (e) { if (e instanceof Error && e.message.startsWith("launch instructions file not found")) { /* fix path or drop setting */ } throw e; }

When it happens

Trigger: Configuration (e.g. agent config or launch flags) points at an instructions appendix path that is missing — relative path resolved against an unexpected cwd, a typo, a file not committed/created, or a worktree where the file exists only on another branch.

Common situations: Teammates cloning a repo where a local uncommitted instructions file is configured; running OMX from a different directory so a relative path no longer resolves; renamed or deleted instruction files after a refactor.

Related errors

• autoresearch_candidate_missing:${candidateFile}
• catalog_manifest_missing
• [ask] --agent-prompt role "${normalizedRole}" not found in $
• ${guidance}Invalid reasoning mode "${mode}". Expected one of
• No mission summary found at ${summaryPath}.

AI-assisted analysis of Yeachan-Heo/oh-my-codex@3ad79a8a6f (2026-08-27). Data as JSON: /api/errors/18ecdad450e16bc0. Report an issue: GitHub.