Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix [BUG] SessionStart prompt hooks crash with unhandled exception [1 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
anthropics/claude-code#48508•Fetched 2026-04-16 06:58:14
View on GitHub
Comments
0
Participants
1
Timeline
4
Reactions
0
Author
ep-ericep-eric
Participants
ep-ericep-eric
Timeline (top)
labeled ×4

A SessionStart hook of type: "prompt" throws an unhandled exception on every session start. The exception message itself reads "This is a bug," suggesting the platform team may already be aware, or it's a generalized catch-all response. Reporting to confirm it is reproducible across platforms and versions, and to document the impact on plugin development.

Error Message

Bug: SessionStart prompt hooks crash with unhandled exception A SessionStart hook of type: "prompt" throws an unhandled exception on every session start. The exception message itself reads "This is a bug," suggesting the platform team may already be aware, or it's a generalized catch-all response. Reporting to confirm it is reproducible across platforms and versions, and to document the impact on plugin development.

Error Messages/Logs

Root Cause

A SessionStart hook of type: "prompt" throws an unhandled exception on every session start. The exception message itself reads "This is a bug," suggesting the platform team may already be aware, or it's a generalized catch-all response. Reporting to confirm it is reproducible across platforms and versions, and to document the impact on plugin development.

Code Example

{               
    "hooks": {
      "SessionStart": [
        {
          "hooks": [                                                                                        
            {
              "type": "prompt",                                                                             
              "prompt": "Your instruction here."
            }
          ]
        }
      ]
    }
  }

---

ToolUseContext is required for prompt hooks. This is a bug.

---

{               
    "hooks": {
      "SessionStart": [
        {
          "hooks": [                                                                                        
            {
              "type": "prompt",                                                                             
              "prompt": "Your instruction here."
            }
          ]
        }
      ]
    }
  }
RAW_BUFFERClick to expand / collapse

Preflight Checklist

  • I have searched existing issues and this hasn't been reported yet
  • This is a single bug report (please file separate reports for different bugs)
  • I am using the latest version of Claude Code

What's Wrong?

Bug: SessionStart prompt hooks crash with unhandled exception

Summary

A SessionStart hook of type: "prompt" throws an unhandled exception on every session start. The exception message itself reads "This is a bug," suggesting the platform team may already be aware, or it's a generalized catch-all response. Reporting to confirm it is reproducible across platforms and versions, and to document the impact on plugin development.

Environment

  • Claude Code version: 2.1.109
  • Platforms: Ubuntu 24.04.4 LTS (x86_64), Raspberry Pi OS Lite 64-bit (aarch64) — reproduced on both

Steps to reproduce

  1. Create a hooks.json with a SessionStart prompt hook:
  {               
    "hooks": {
      "SessionStart": [
        {
          "hooks": [                                                                                        
            {
              "type": "prompt",                                                                             
              "prompt": "Your instruction here."
            }
          ]
        }
      ]
    }
  }
  1. Start a new Claude Code session.

Actual behavior

The session crashes immediately with:

ToolUseContext is required for prompt hooks. This is a bug.

Expected behavior

The prompt hook fires at session start and the model executes the instruction before the user's first message.

Additional notes

  • type: "command" hooks at SessionStart work — but only inject output as a <system-reminder>. The model does not act on it until the user sends their first message, making it unsuitable for auto-executing instructions on open.
  • ${CLAUDE_PLUGIN_ROOT} expands correctly in command hooks but not in prompt hooks.
  • The primary use case blocked by this bug: plugins that need to auto-run a startup routine (e.g. load session context, deliver a sitrep, custom greeting/instruction) when a session opens, without requiring the user to type a command first.

What Should Happen?

The prompt hook fires at session start and the model executes the instruction before the user's first message.

Error Messages/Logs

ToolUseContext is required for prompt hooks. This is a bug.

Steps to Reproduce

  1. Create a hooks.json with a SessionStart prompt hook:
{               
  "hooks": {
    "SessionStart": [
      {
        "hooks": [                                                                                        
          {
            "type": "prompt",                                                                             
            "prompt": "Your instruction here."
          }
        ]
      }
    ]
  }
}
  1. Start a new Claude Code session.

Claude Model

Sonnet (default)

Is this a regression?

I don't know

Last Working Version

No response

Claude Code Version

2.1.109

Platform

Anthropic API

Operating System

Ubuntu/Debian Linux

Terminal/Shell

Terminal.app (macOS)

Additional Information

No response

extent analysis

TL;DR

The issue can be mitigated by using a "command" hook instead of a "prompt" hook for SessionStart, although this may not fully achieve the desired behavior of auto-executing instructions on session open.

Guidance

  • The error message suggests that a ToolUseContext is required for prompt hooks, which is not being provided, causing the session to crash.
  • Using a "command" hook at SessionStart may be a temporary workaround, but it only injects output as a <system-reminder> and does not allow the model to act on it until the user sends their first message.
  • The primary use case blocked by this bug is plugins that need to auto-run a startup routine without requiring user input, which may need to be re-designed or postponed until the bug is fixed.
  • To verify the issue, create a hooks.json file with a SessionStart prompt hook and start a new Claude Code session, which should crash immediately with the error message.

Example

No code snippet is provided as the issue is more related to the configuration and usage of the Claude Code platform rather than a specific code problem.

Notes

The provided information suggests that the bug is present in the latest version of Claude Code (2.1.109) and is reproducible across different platforms (Ubuntu and Raspberry Pi OS Lite). However, without further information or a clear indication of how to provide the required ToolUseContext, a full solution cannot be provided.

Recommendation

Apply workaround: Use a "command" hook instead of a "prompt" hook for SessionStart, although this may not fully achieve the desired behavior. This is because the "command" hook is the only alternative provided in the issue that does not crash the session, even if it does not fully meet the requirements.

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

The prompt hook fires at session start and the model executes the instruction before the user's first message.

#api#ssr#latency issue#model loading#dependency error

Still need to ship something?

×6

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

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix [BUG] SessionStart prompt hooks crash with unhandled exception [1 participants]