oraios/serena · error · ValueError

Session ID is required in the hook input data

Error message

Session ID is required in the hook input data

What it means

SerenaAgentHook.__init__ parses the hook's stdin JSON and requires a session_id (or sessionId) field to build the per-session persistence directory under serena_home/hook_data. If the hook input payload lacks it, ValueError is raised.

Source

Thrown at src/serena/hooks.py:40

    """The client application that triggered the hook."""

    CLAUDE_CODE = "claude-code"
    CODEBUDDY = "codebuddy"
    VSCODE = "vscode"
    CODEX = "codex"
    GROK = "grok"


class Hook(ABC):
    def __init__(self, client: HookClient):
        raw = sys.stdin.read()
        input_data = json.loads(raw, strict=False)
        self._input_data = input_data
        self._client = client

        session_id = input_data.get("session_id") or input_data.get("sessionId")
        if not session_id:
            raise ValueError("Session ID is required in the hook input data")
        self._session_id = str(session_id)
        self.session_persistence_dir = os.path.join(serena_home_dir, "hook_data", self._session_id)
        # tool input has a timestamp but using now is enough
        self.triggered_at_timestamp = datetime.now()

    @abstractmethod
    def execute(self) -> None:
        pass


class PreToolUseHook(Hook, ABC):
    _NON_SYMBOLIC_SERENA_TOOL_NAME_SUBSTRINGS = frozenset(
        (
            "pattern",
            "read",
            "diagnostics",
            "memory",
            "onboarding",

View on GitHub (pinned to 7fcbca7e62)

Solutions

1. Ensure the hook input JSON includes "session_id" (or "sessionId") with a non-empty value
2. Update the agent/hook client to a version that forwards session ids
3. Validate your hook payload schema before registering hooks

Example fix

// before
{"hook_event_name": "PreToolUse"}
// after
{"hook_event_name": "PreToolUse", "session_id": "abc-123"}

def validate_hook_input(data: dict) -> None:
    sid = data.get("session_id") or data.get("sessionId")
    if not sid:
        raise ValueError("hook input JSON must include a non-empty session_id")

try:
    hook = SerenaAgentHook(client)
except ValueError as e:
    if "Session ID" in str(e):
        logging.error("Hook payload missing session_id: fix the hook client payload")
    else:
        raise

When it happens

Trigger: A hook client (e.g. Claude Code hook or custom HookClient) invokes a Serena hook with JSON input missing both 'session_id' and 'sessionId' keys, or with null/empty values.

Common situations: Writing a custom hook integration that forgets to forward the session id; an agent CLI updating its hook schema/field name; manually testing hooks with hand-crafted JSON.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• Tool name is required in the hook input data
• Cannot use both fixed_tools and excluded_tools/included_opti
• Unknown language backend '{backend_str}': valid values are {
• Invalid line_ending: {value!r}. Valid values are: {valid}
• Invalid language server: '{orig_language_str}'.\nValid value

AI-assisted analysis of oraios/serena@7fcbca7e62 (2026-08-29). Data as JSON: /api/errors/c3dc6ceea41032e1. Report an issue: GitHub.