charmbracelet/crush · error

session ID is required for creating a new file

Error message

session ID is required for creating a new file

What it means

The fetch tool requires a session ID from the tool context before it can request permission to access the URL. If the context has no session ID, this error (with a copy-pasted 'creating a new file' message from the edit tool) is returned. The message text is misleading; the real issue is a missing session in the context.

Source

Thrown at internal/agent/tools/fetch.go:77

		FetchToolName,
		fetchDescription(),
		func(ctx context.Context, params FetchParams, call fantasy.ToolCall) (fantasy.ToolResponse, error) {
			if params.URL == "" {
				return fantasy.NewTextErrorResponse("URL parameter is required"), nil
			}

			format := strings.ToLower(params.Format)
			if format != "text" && format != "markdown" && format != "html" {
				return fantasy.NewTextErrorResponse("Format must be one of: text, markdown, html"), nil
			}

			if !strings.HasPrefix(params.URL, "http://") && !strings.HasPrefix(params.URL, "https://") {
				return fantasy.NewTextErrorResponse("URL must start with http:// or https://"), nil
			}

			sessionID := GetSessionFromContext(ctx)
			if sessionID == "" {
				return fantasy.ToolResponse{}, fmt.Errorf("session ID is required for creating a new file")
			}

			p, err := permissions.Request(
				ctx,
				permission.CreatePermissionRequest{
					SessionID:   sessionID,
					Path:        workingDir,
					ToolCallID:  call.ID,
					ToolName:    FetchToolName,
					Action:      "fetch",
					Description: fmt.Sprintf("Fetch content from URL: %s", params.URL),
					Params:      FetchPermissionsParams(params),
				},
			)
			if err != nil {
				return fantasy.ToolResponse{}, err
			}
			if !p {

View on GitHub (pinned to 7944b8e522)

Solutions

1. Attach the session ID to the context via the session-context helper before calling the tool.
2. Use the agent runtime's context rather than a bare context.Background().
3. In tests, replicate the coordinator's context setup (session middleware).
4. Ignore the misleading wording: treat it exactly like the edit tool's missing-session error.

Example fix

// before
ctx := context.Background()
resp, _ := fetchTool.Run(ctx, params)
// after
ctx := tools.WithSessionContext(context.Background(), "sess_123")
resp, _ := fetchTool.Run(ctx, params)

func requireFetchSession(ctx context.Context) error {
	if tools.GetSessionFromContext(ctx) == "" {
		return errors.New("fetch tool requires a session-scoped context")
	}
	return nil
}

if strings.Contains(err.Error(), "session ID is required") {
	// attach session via WithSessionContext and retry; note the message wording is a known copy-paste artifact
}

When it happens

Trigger: Calling the fetch tool with a context that lacks the session ID — direct/programmatic invocations, tests, or custom runners that bypass the agent's session middleware. URL format is validated first, so this fires only after the URL passes the http/https check.

Common situations: Integration tests calling the fetch tool directly, plugin/scripted usage that builds its own context, refactors dropping session injection.

Related errors

• session id missing from context
• session id missing from context
• session ID is required for downloading files
• session ID is required for creating a new file
• %s

AI-assisted analysis of charmbracelet/crush@7944b8e522 (2026-08-29). Data as JSON: /api/errors/0b5adce06ca473a3. Report an issue: GitHub.