stablyai/orca · error · Error

A Codex home directory path is required.

Error message

A Codex home directory path is required.

What it means

Thrown by importCodexAuthFromHome when the sourceHome argument trims to an empty string. addAccountFromHome expects a path to an already-authenticated CODEX_HOME to copy auth.json from; an empty/whitespace path is a caller bug, not an environment condition.

Source

Thrown at src/main/codex-accounts/service.ts:764

      this.importCodexAuthFromHome(sourceHome, managedHomePath, accountId)
      return await this.persistCapturedCodexAccount(accountId, managedHome)
    } catch (error) {
      this.safeRemoveManagedHome(managedHomePath, accountId)
      throw error
    }
  }

  // Why: copy the auth.json from an already-authenticated CODEX_HOME (e.g. a temp
  // dir the CLI ran `codex login` into) into the managed home. Mirrors the login
  // step of doAddAccount without spawning an interactive browser flow.
  private importCodexAuthFromHome(
    sourceHome: string,
    managedHomePath: string,
    accountId: string
  ): void {
    const trimmed = sourceHome.trim()
    if (!trimmed) {
      throw new Error('A Codex home directory path is required.')
    }
    const authPath = join(resolve(trimmed), 'auth.json')
    if (!existsSync(authPath)) {
      throw new Error(
        `No Codex credentials found in ${resolve(trimmed)}. Run \`codex login\` into this directory first.`
      )
    }
    const trustedHome = this.assertManagedHomePath(managedHomePath, accountId)
    writeFileAtomically(join(trustedHome, 'auth.json'), readFileSync(authPath, 'utf-8'), {
      mode: 0o600
    })
  }

  private async persistCapturedCodexAccount(
    accountId: string,
    managedHome: ManagedHomeLocation
  ): Promise<CodexRateLimitAccountsState> {
    const identity = this.readIdentityFromHome(managedHome.managedHomePath, accountId)

View on GitHub (pinned to 1136503c6a)

Solutions

1. Validate and reject the empty sourceHome at the caller/CLI boundary before invoking addAccountFromHome.
2. Supply the actual CODEX_HOME directory that ran `codex login`.
3. If the user has no pre-authenticated home, use the interactive addAccount() flow instead of addAccountFromHome().

Example fix

// before
service.addAccountFromHome(input || '') // throws [908] when input empty

// after: validate at the boundary
if (!sourceHome?.trim()) { throw new Error('Pass the CODEX_HOME that ran `codex login`') }
await service.addAccountFromHome(sourceHome, target)

// Reject an empty source home before importing.
if (!sourceHome || !sourceHome.trim()) {
  throw new Error('A CODEX_HOME path is required for import.')
}
await service.addAccountFromHome(sourceHome, target)

const isNonEmptyHomePath = (value: string | undefined | null): value is string =>
  typeof value === 'string' && value.trim().length > 0

try {
  await service.addAccountFromHome(sourceHome, target)
} catch (error) {
  if (error instanceof Error && error.message === 'A Codex home directory path is required.') {
    // prompt the user for the CODEX_HOME path
  } else throw error
}

When it happens

Trigger: Calling addAccountFromHome('') or addAccountFromHome(' ') (or passing an undefined-coerced string) from the 'orca account add --agent codex' CLI import path (service.ts:735).

Common situations: CLI argument not supplied (--agent codex without a home path), a form field left blank, or a caller passing `undefined` that was stringified.

Related errors

• No Codex credentials found in ${resolve(trimmed)}. Run `code
• That Codex account belongs to a different runtime.
• That Codex rate limit account no longer exists.
• Package version is not valid semver: ${baseVersion}
• Adhoc build timestamp is invalid.

AI-assisted analysis of stablyai/orca@1136503c6a (2026-08-12). Data as JSON: /api/errors/e97b4002f20ca13b. Report an issue: GitHub.