github/github-mcp-server · warning

missing required parameter: ref

Error message

missing required parameter: ref

What it means

The MCP completions/complete handler received a request whose Params or Params.Ref is nil. The MCP spec requires every completion request to carry a ref (ref/prompt with a name, or ref/resource with a uri); the server fails fast rather than guessing what to complete.

Source

Thrown at pkg/github/server.go:195

	if title == "" {
		title = "GitHub MCP Server"
	}

	// Create a new MCP server
	s := mcp.NewServer(&mcp.Implementation{
		Name:    name,
		Title:   title,
		Version: version,
		Icons:   octicons.Icons("mark-github"),
	}, opts)

	return s
}

func CompletionsHandler(getClient GetClientFn) func(ctx context.Context, req *mcp.CompleteRequest) (*mcp.CompleteResult, error) {
	return func(ctx context.Context, req *mcp.CompleteRequest) (*mcp.CompleteResult, error) {
		if req == nil || req.Params == nil || req.Params.Ref == nil {
			return nil, fmt.Errorf("missing required parameter: ref")
		}
		switch req.Params.Ref.Type {
		case "ref/resource":
			if strings.HasPrefix(req.Params.Ref.URI, "repo://") {
				return RepositoryResourceCompletionHandler(getClient)(ctx, req)
			}
			return nil, fmt.Errorf("unsupported resource URI: %s", req.Params.Ref.URI)
		case "ref/prompt":
			return nil, nil
		default:
			return nil, fmt.Errorf("unsupported ref type: %s", req.Params.Ref.Type)
		}
	}
}

func MarshalledTextResult(v any) *mcp.CallToolResult {
	data, err := json.Marshal(v)
	if err != nil {

View on GitHub (pinned to 0ea1f775a7)

Solutions

1. Fix the client to always include ref with a valid type (ref/prompt or ref/resource)
2. If writing a client, verify serialization keeps non-zero ref fields
3. Server operators: capture the client name/version from request logs to identify the offender

// client-side, before sending completion/complete
if req.Params == nil || req.Params.Ref == nil {
	return fmt.Errorf("refusing to send completion request without ref")
}

When it happens

Trigger: An MCP client sends complete with an empty params object, omits ref, or serializes ref as an omitempty pointer that gets dropped; hand-rolled test harnesses posting partial JSON.

Common situations: Buggy or experimental clients; SDK versions where ref is a pointer that is easy to leave unset; probing scripts that fire completion before full initialization.

Related errors

• owner or repo not specified
• each issue_fields item must be an object
• issue_fields must be an array
• field_name is required for each issue_fields item
• value cannot be null for field %q

AI-assisted analysis of github/github-mcp-server@0ea1f775a7 (2026-08-15). Data as JSON: /api/errors/84ae1cca24a9df85. Report an issue: GitHub.