Skip to content

codex-cli 0.124.0 fails to start when hook config is present and codex_hooks is enabled #19199

Closed
Closed
codex-cli 0.124.0 fails to start when hook config is present and codex_hooks is enabled#19199
Labels
bugSomething isn't workingconfigIssues involving config.toml, config keys, config merging, or config updateshooksIssues related to event hooksregressionBehaviors that worked in previous versions but were broken due to an update

Description

@elmakus
elmakus
opened on Apr 23, 2026

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/codex@0.124.0
  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/codex@0.124.0
  • 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.

Activity

  1. github-actions
    added
    bugSomething isn't working
    CLIIssues related to the Codex CLI
    hooksIssues related to event hooks
    configIssues involving config.toml, config keys, config merging, or config updates
    on Apr 23, 2026

  2. zyz23333 commented on Apr 23, 2026

    @zyz23333
    zyz23333
    on Apr 23, 2026

    Same issue to me.Both on CLI and Windows app.

  3. etraut-openai
    added
    regressionBehaviors that worked in previous versions but were broken due to an update
    and removed
    CLIIssues related to the Codex CLI
    on Apr 23, 2026

  4. eternal-openai commented on Apr 23, 2026

    @eternal-openai
    eternal-openai
    on Apr 23, 2026
    Contributor

    Problem is GSD's as far as I can tell:

    • I could not repro using just the "Reproduction" steps
    • however the hint was the [[hooks]] message. Apparently, GSD used to insert this into our config, though it's not a standard config format for us. It just happened to not be marked as invalid before
    • what changed? We actually do support hooks in toml now, in addition to json (though the docs update isn't live yet). So that's what caused the conflict with GSD's "augmentation" of our config. The following works
    [[hooks.SessionStart]]
matcher = "startup|resume"

[[hooks.SessionStart.hooks]]
type = "command"
command = "echo hi"

    but this does not:

    [[hooks]]
event = "SessionStart"
command = "echo hi"
  5. eternal-openai
    closed this as completedon Apr 23, 2026
  6. rodion-m
    added a commit that references this issue on Apr 25, 2026

    Update Codex hooks reference for v0.124.0 stable hooks (April 2026)

    87171ff
  7. abhinav-oai
    marked Error starting chat - invalid configuration #19364 as a duplicate of this issue on Apr 28, 2026

  8. oxysoft commented on May 8, 2026

    @oxysoft
    oxysoft
    on May 8, 2026

    Indexed this hook ticket in the umbrella tracker: #21753

    Goal: collect the scattered Codex hook requests and bugs into one parity matrix for Full Claude Code Hook Parity (29+), while preserving this issue as the detailed thread for its specific behavior.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingconfigIssues involving config.toml, config keys, config merging, or config updateshooksIssues related to event hooksregressionBehaviors that worked in previous versions but were broken due to an update

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions