Issue Station
Sign In
Tools hereToolbox

codex - 💡(How to fix) Fix codex-cli 0.124.0 fails to start when hook config is present and codex_hooks is enabled [2 comments, 3 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
openai/codex#19199•Fetched 2026-04-24 05:58:56
View on GitHub
Comments
2
Participants
3
Timeline
10
Reactions
2
Author
elmakuselmakus
Participants
elmakuselmakuseternal-openaieternal-openaizyz23333zyz23333
Timeline (top)
labeled ×5commented ×2closed ×1cross-referenced ×1

codex-cli 0.124.0 fails to start when hook configuration is present and features.codex_hooks = true.

The CLI exits with:

Error loading config.toml: invalid type: map, expected a sequence
in `hooks`

The current docs say hooks should live in ~/.codex/hooks.json or <repo>/.codex/hooks.json, not inside config.toml:

Error Message

Error loading config.toml: invalid type: map, expected a sequence Codex should start and load the hook configuration, or at minimum emit a validation error that points to hooks.json if the JSON schema is wrong. Error loading config.toml: invalid type: map, expected a sequence The error mentions config.toml and hooks, even though the documented hook configuration lives in hooks.json.

  • I also hit the same error when a legacy [[hooks]] block is present in config.toml. Please verify whether 0.124.0 regressed hook config loading, especially the documented hooks.json path and error reporting.

Root Cause

codex-cli 0.124.0 fails to start when hook configuration is present and features.codex_hooks = true.

The CLI exits with:

Error loading config.toml: invalid type: map, expected a sequence
in `hooks`

The current docs say hooks should live in ~/.codex/hooks.json or <repo>/.codex/hooks.json, not inside config.toml:

Code Example

Error loading config.toml: invalid type: map, expected a sequence
in `hooks`

---

[features]
codex_hooks = true

---

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "echo hi"
          }
        ]
      }
    ]
  }
}

---

CODEX_HOME="$TMP" codex features list

---

Error loading config.toml: invalid type: map, expected a sequence
in `hooks`

---

[features]
codex_hooks = false
RAW_BUFFERClick to expand / collapse

Summary

codex-cli 0.124.0 fails to start when hook configuration is present and features.codex_hooks = true.

The CLI exits with:

Error loading config.toml: invalid type: map, expected a sequence
in `hooks`

The current docs say hooks should live in ~/.codex/hooks.json or <repo>/.codex/hooks.json, not inside config.toml:

Impact

This blocks upgrading to 0.124.0 for installations that use Codex hooks. In practice it breaks real setups that enable codex_hooks, including GSD-installed Codex hook integrations.

Reproduction

I can reproduce this on Linux with a minimal temporary CODEX_HOME.

  1. Install @openai/[email protected]
  2. Create a temp config directory
  3. Write this config.toml:
[features]
codex_hooks = true
  1. Write this hooks.json next to it:
{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "echo hi"
          }
        ]
      }
    ]
  }
}
  1. Run Codex against that config:
CODEX_HOME="$TMP" codex features list

Expected behavior

Codex should start and load the hook configuration, or at minimum emit a validation error that points to hooks.json if the JSON schema is wrong.

Actual behavior

Codex exits immediately with:

Error loading config.toml: invalid type: map, expected a sequence
in `hooks`

The error mentions config.toml and hooks, even though the documented hook configuration lives in hooks.json.

Additional notes

  • I also hit the same error when a legacy [[hooks]] block is present in config.toml.
  • If I disable hooks entirely with:
[features]
codex_hooks = false

then 0.124.0 starts normally.

  • This makes the regression look specific to the hook loader / hook config parsing path.

Environment

  • Codex CLI: 0.124.0
  • Install method: npm install -g @openai/[email protected]
  • Node: v24.14.1
  • npm: 11.11.0
  • OS: Linux 6.17.0-22-generic x86_64

Proposed next step

Please verify whether 0.124.0 regressed hook config loading, especially the documented hooks.json path and error reporting.

extent analysis

TL;DR

Remove or refactor the hooks configuration from config.toml to fix the error.

Guidance

  • Verify that the hooks.json file is correctly formatted and located in the expected path (~/.codex/hooks.json or <repo>/.codex/hooks.json).
  • Check for any legacy [[hooks]] blocks in config.toml and remove them, as they may be causing the error.
  • If using a custom config.toml, ensure that it does not contain any hooks configuration, as this is no longer supported.
  • Test the Codex CLI with the updated configuration to confirm that the error is resolved.

Example

No code snippet is provided, as the issue is related to configuration files and not code.

Notes

The error message suggests that the hooks configuration in config.toml is no longer supported, and the documented hooks.json path should be used instead. Removing or refactoring the hooks configuration from config.toml should resolve the error.

Recommendation

Apply the workaround by removing or refactoring the hooks configuration from config.toml, as the error is specific to the hook loader/config parsing path and disabling hooks entirely resolves the issue.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

FAQ

Expected behavior

Codex should start and load the hook configuration, or at minimum emit a validation error that points to hooks.json if the JSON schema is wrong.

#installation#prompt issue#agent setup#task chaining#parallel task

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING