openai/codex · error · CodexError

timed out waiting for goal turn to start after {int(_GOAL_ST

Error message

timed out waiting for goal turn to start after {int(_GOAL_START_TIMEOUT_S)} seconds

What it means

Error "timed out waiting for goal turn to start after {int(_GOAL_START_TIMEOUT_S)} seconds" thrown in openai/codex.

Source

Thrown at sdk/python/src/openai_codex/client.py:590

            raise InvalidRequestError(
                -32600,
                f"thread must be persisted before starting a goal: {thread_id}",
            )

        state = self.reserve_goal_operation(thread_id)
        activated = False
        try:
            self.thread_goal_clear(thread_id)
            state.activate_turn_routing()
            self.thread_goal_set(
                thread_id,
                objective=objective,
                status=ThreadGoalStatus.active,
            )
            activated = True
            turn_id = state.wait_for_start(_GOAL_START_TIMEOUT_S)
            if turn_id is None:
                raise CodexError(
                    "timed out waiting for goal turn to start after "
                    f"{int(_GOAL_START_TIMEOUT_S)} seconds"
                )
            return state, turn_id
        except BaseException as exc:
            if activated or not isinstance(exc, InvalidRequestError):
                self.cancel_goal_operation(state)
            state.finish()
            self.unregister_goal_operation(state)
            raise

    def turn_start(
        self,
        thread_id: str,
        input_items: list[JsonObject] | JsonObject | str,
        params: V2TurnStartParams | JsonObject | None = None,
    ) -> TurnStartResponse:
        """Start a turn and register its notification queue as early as possible."""

View on GitHub (pinned to 339751715c)

Solutions

1. Check that the Codex runtime is healthy and responsive, then retry starting the goal; investigate runtime logs for the stall.

When it happens

Trigger: Thrown at sdk/python/src/openai_codex/client.py:590 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of openai/codex@339751715c (2026-08-25). Data as JSON: /api/errors/677e049ea28fbe2e. Report an issue: GitHub.