jaegertracing/jaeger · error

tools[%d].name is empty or whitespace

Error message

tools[%d].name is empty or whitespace

What it means

validateContextualToolNames checks every contextual tool in an incoming AI request has a non-empty, non-whitespace name and reports the first offending index. It throws this so the frontend developer can locate the broken tool declaration, without exposing any user content from the rest of the request.

Source

Thrown at cmd/jaeger/internal/extension/jaegerquery/internal/jaegerai/translation.go:64

	return result
}

// validateContextualToolNames rejects requests carrying tools with empty
// or whitespace-only names. Such names would prefix to "ui_" / "ui_   ",
// which the dispatcher's handleJaegerToolCall later rejects as
// InvalidParams and which would land in both NewSessionRequest.Meta and
// ContextualToolsStore as unusable entries. Returning a 400 from the
// caller (handler.go) keeps both data structures clean and surfaces
// frontend bugs immediately instead of allowing them to fail mid-turn
// after a sidecar round-trip.
//
// The reported error names the first offending tool index so the
// frontend developer can locate the broken declaration; it does not
// reveal any user content from the rest of the request.
func validateContextualToolNames(tools []aguitypes.Tool) error {
	for i, tool := range tools {
		if strings.TrimSpace(tool.Name) == "" {
			return fmt.Errorf("tools[%d].name is empty or whitespace", i)
		}
	}
	return nil
}

// prefixContextualTools returns a copy of the supplied tools with each
// name prefixed by UIToolPrefix. The original slice is not mutated so the
// caller can keep it for logging/inspection. Empty input returns nil so
// callers can branch on the length to decide whether to attach Meta and
// SetForSession at all.
//
// Callers must invoke validateContextualToolNames first to guarantee no
// blank names slip through. This function does not re-validate so a stray
// caller cannot accidentally bypass the boundary check.
func prefixContextualTools(tools []aguitypes.Tool) []aguitypes.Tool {
	if len(tools) == 0 {
		return nil
	}

View on GitHub (pinned to 806f444784)

Solutions

1. Fix the tool at the reported index in the request payload so its name is a non-empty trimmed string.
2. Add client-side validation that rejects tool entries with blank names before sending.
3. Confirm the frontend and jaegerquery versions agree on the request schema.

Example fix

// before
"tools": [{"name": ""}, {"name": "search"}]
// after
"tools": [{"name": "get_trace"}, {"name": "search"}]

func toolsValid(tools []aguitypes.Tool) error {
    for i, t := range tools {
        if strings.TrimSpace(t.Name) == "" {
            return fmt.Errorf("tools[%d].name is empty or whitespace", i)
        }
    }
    return nil
}
// call before issuing the request
if err := toolsValid(tools); err != nil { return err }

func hasValidName(t aguitypes.Tool) bool {
    return strings.TrimSpace(t.Name) != ""
}

resp, err := http.Post(url, "application/json", body)
if err != nil { return err }
if resp.StatusCode == http.StatusBadRequest {
    b, _ := io.ReadAll(resp.Body)
    return fmt.Errorf("tool declaration rejected: %s", b)
}

When it happens

Trigger: POSTing a request to the jaegerquery AI HTTP endpoint whose tools array contains a Tool with Name == "" or only whitespace at index i.

Common situations: Frontend builds the tools array programmatically and a tool object failed to populate its name; schema drift between frontend and backend versions; JSON with a typo like "nmae".

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• unable to parse param '%s': %w
• trace_id is required
• start_time must be before end_time
• trace_id is required
• span_ids is required and must not be empty

AI-assisted analysis of jaegertracing/jaeger@806f444784 (2026-09-01). Data as JSON: /api/errors/f569b85cfc570bfa. Report an issue: GitHub.