Error starting chat - invalid configuration

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• #19353
• #19199

Powered by Codex Action

Claude Code solved it:

User approved Claude's plan
⎿  Plan saved to:
~/.claude/plans/when-using-codex-app-snug-brook.md · /plan
to edit
Fix Codex.app "Invalid configuration: invalid type: map,
expected a sequence in 'hooks'"

Context

When launching chat in the Codex macOS app inside this repo,
startup fails with:

▎ Error starting chat
▎ Invalid configuration: invalid type: map, expected a
▎ sequence in 'hooks'

Root cause: Current Codex versions changed how they parse
the hooks key in config.toml and now reject the [[hooks]]
array-of-tables format that GSD's installer wrote. This is a
known regression tracked upstream in GSD
(gsd-build/get-shit-done#2637) and in codex itself — the
[[hooks]] sequence previously used by GSD no longer matches
Codex's expected schema, so the app refuses to start.

Current state of
/Users/<hidden>/Developer/<hidden>/.codex/config.toml
(lines 140–143):

# GSD Hooks
[[hooks]]
event = "SessionStart"
command = "node /Users/<hidden>/Developer/<hidden>/.codex
/hooks/gsd-check-update.js"

And line 5:

[features]
codex_hooks = true

The only hook registered is a non-critical background GSD
update checker — disabling it has no functional impact on
GSD or Codex day-to-day work.

Your versions:

• codex-cli CLI: 0.122.0
• Codex.app (desktop): 26.422.21637

Fix

Disable the hooks block so Codex.app parses the config
successfully. Two edits to .codex/config.toml:

1. Flip the GSD flag (so GSD knows hooks are intentionally

off and won't re-add them on its next install/update pass):

1. Line 5:

• codex_hooks = true
• codex_hooks = false

1. Remove the [[hooks]] block at the bottom of the file

(lines 140–143 — the # GSD Hooks comment, [[hooks]] table,
event, and command lines). This is the line actually
triggering the TOML parse rejection in Codex.app.

After the edit, the file should end at line 137
([agents.gsd-verifier] block) with no trailing [[hooks]]
section.

Files touched

• /Users/<hidden>/Developer/<hidden>/.codex/config.toml

(only)

Nothing else needs to change — ~/.codex/config.toml (global)
has no hooks section, and no other .codex/config.toml in
the repo references [[hooks]].

Verification

1. Open Codex.app on this project. The "Error starting chat"

dialog should no longer appear and chat should start
normally.

1. From the terminal in the repo, run codex --version

(sanity check CLI still works — it was working before,
should continue to).

1. Confirm GSD still behaves — run any /gsd-* command from

Claude Code; they don't depend on the Codex session-start
hook.

Follow-up (not in scope now)

If/when GSD ships a fix for #2637 that uses the new hook
format, re-enable by flipping codex_hooks = true and
re-running the GSD installer so it writes the new-format
hooks block. Until then, leave off.

⏺ Update(.codex/config.toml)
⎿  Added 1 line, removed 1 line
2 # GSD codex_hooks ownership: section
3
4 [features]
5 -codex_hooks = true
5 +codex_hooks = false
6
7 [agents.gsd-advisor-researcher]
8 description = "Researches a single gray area deci
sion and returns a structured comparison table wi
th rationale. Spawned by discuss-phase advisor mo
de."

⏺ Update(.codex/config.toml)
⎿  Removed 5 lines
136 description = "Verifies phase goal achievement
through goal-backward analysis. Checks codebase
delivers what phase promised, not just that ta
sks completed. Creates VERIFICATION.md report."
137 config_file = "/Users/<hidden>/Developer/<hidden>/.codex/agents/gsd-verifier.toml"
138
139 -
140 -# GSD Hooks
141 -[[hooks]]
142 -event = "SessionStart"
143 -command = "node /Users/<hidden>/Developer/<hidden>/.codex/hooks/gsd-check-update.js"

Searched for 1 pattern (ctrl+o to expand)

⏺ Done. codex_hooks = false set and the [[hooks]] block removed.
Relaunch Codex.app and the "Error starting chat" should be
gone.

Sources:

• https://github.com/gsd-build/get-shit-done/issues/2637
• https://github.com/openai/codex/issues/17532

This issue was already resolved here, I think you can close it:

https://github.com/openai/codex/issues/19199

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.