EveryInc/compound-engineering-plugin · critical · Error

HOME is not set

Error message

HOME is not set

What it means

resolveCodexDevContext reads HOME from the environment to locate $CODEX_HOME or ~/.codex and resolve home-relative paths. If HOME is unset or empty it throws immediately, because every subsequent path resolution would be meaningless. This is a hard precondition, not a recoverable state.

Source

Thrown at src/dev/codex-dev.ts:178

  for (const entry of entries) {
    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue
    try {
      const stat = await fs.stat(path.join(skillsRoot, entry.name, "SKILL.md"))
      if (stat.isFile()) names.push(entry.name)
    } catch (error) {
      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error
    }
  }
  return names.sort()
}

export async function resolveCodexDevContext(
  cwd: string,
  env: NodeJS.ProcessEnv = process.env,
  runner: CommandRunner = new BunCommandRunner(),
): Promise<CodexDevContext> {
  const home = env.HOME
  if (!home) throw new Error("HOME is not set")

  const options = { cwd, env }
  const repoRootRaw = trim(await checkedRun(runner, "git", ["rev-parse", "--show-toplevel"], options))
  const repoRoot = await fs.realpath(repoRootRaw)
  await assertCompoundEngineeringRepo(repoRoot)

  const gitDir = trim(
    await checkedRun(runner, "git", ["rev-parse", "--path-format=absolute", "--absolute-git-dir"], {
      cwd: repoRoot,
      env,
    }),
  )
  const gitCommonDir = trim(
    await checkedRun(runner, "git", ["rev-parse", "--path-format=absolute", "--git-common-dir"], {
      cwd: repoRoot,
      env,
    }),
  )

View on GitHub (pinned to c9c10f8c75)

Solutions

1. Export HOME in the current shell: export HOME=/home/<user>, then re-run.
2. If invoked from a service/CI, add HOME to the job's environment block.
3. Alternatively set CODEX_HOME explicitly — but note HOME is still required by this code path, so fix HOME regardless.
4. In tests, pass a complete fake env: { ...process.env, HOME: tmpDir }.

Example fix

// before: test setup
const ctx = await resolveCodexDevContext(cwd, { PATH: "/usr/bin" })
// after
const ctx = await resolveCodexDevContext(cwd, { PATH: "/usr/bin", HOME: tmpHome })

if (!process.env.HOME) {
  throw new Error("HOME must be set before running codex:dev (export HOME=/home/<user>)")
}

try {
  await resolveCodexDevContext(cwd)
} catch (error) {
  if ((error as Error).message === "HOME is not set") {
    console.error("Set HOME in your environment (shell profile, CI env block, or env -i fallback)")
    process.exitCode = 1
  } else throw error
}

When it happens

Trigger: Calling resolveCodexDevContext (via the context/firstContext/makeContext helpers or the CLI) with env.HOME undefined or empty string — e.g. a stripped environment passed as the second argument, or a shell/service with no HOME set (src/dev/codex-dev.ts:178).

Common situations: Running the CLI under cron/systemd/CI with a minimal env; invoking via env -i or a container exec without -e HOME; a test passing a hand-built env object that forgot HOME.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Could not read ${filePath}: ${error instanceof Error ? error
• ${repoRoot} is not the compound-engineering repository
• Could not inspect ${configPath}: ${error instanceof Error ?

AI-assisted analysis of EveryInc/compound-engineering-plugin@c9c10f8c75 (2026-08-31). Data as JSON: /api/errors/fb65a765757623e4. Report an issue: GitHub.