googleapis/mcp-toolbox · error

executePipeline API error (status %d): %s

Error message

executePipeline API error (status %d): %s

What it means

This error indicates the Firestore executePipeline REST API returned a non-2xx status code. The error message embeds both the numeric HTTP status and the raw response body, which for Google APIs is usually a JSON error object with a human-readable message explaining the failure (bad pipeline syntax, permission denied, missing index, etc.).

Source

Thrown at internal/sources/firestore/firestore.go:936

	}
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("User-Agent", userAgent)
	req.Header.Set("x-goog-request-params", fmt.Sprintf("project_id=%s&database_id=%s", s.GetProjectId(), s.GetDatabaseId()))
	req.Header.Set("x-goog-firestore-api-requester", "querydata")

	resp, err := httpClient.Do(req)
	if err != nil {
		return nil, fmt.Errorf("failed to execute pipeline request: %w", err)
	}
	defer resp.Body.Close()

	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return nil, fmt.Errorf("failed to read response body: %w", err)
	}

	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
		return nil, fmt.Errorf("executePipeline API error (status %d): %s", resp.StatusCode, string(respBody))
	}

	var result any
	if err := json.Unmarshal(respBody, &result); err != nil {
		return string(respBody), nil
	}

	return result, nil
}

func initFirestoreConnection(
	ctx context.Context,
	tracer trace.Tracer,
	name string,
	project string,
	database string,
) (*firestore.Client, error) {
	ctx, span := sources.InitConnectionSpan(ctx, tracer, SourceType, name)

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read the embedded response body in the error — Google's JSON error message pinpoints the exact problem (invalid argument, permission, not found)
2. Validate the MQL pipeline syntax (stage names, aggregate functions) — 400s are usually pipeline mistakes
3. Verify credentials/permissions: enable the Firestore API, grant the service account appropriate datastore roles
4. Check status 429/5xx and retry with exponential backoff

Example fix

// before
pipeline := "{documents: {path: 'users`'}}" // bad syntax
res, _ := src.ExecuteMQL(ctx, pipeline)
// after
pipeline := "{documents: {path: 'users'}}"
res, err := src.ExecuteMQL(ctx, pipeline)
if err != nil { log.Printf("executePipeline failed: %v", err) } // body shows API reason

// validate before calling: credentials + API enabled
creds, err := google.FindDefaultCredentials(ctx)
if err != nil { log.Fatal("no ADC: ", err) }

res, err := src.ExecuteMQL(ctx, pipeline)
if err != nil {
    var apiErr struct {
        Error struct{ Code int; Message string } `json:"error"`
    }
    if m := regexp.MustCompile(`status (\d+)\): (.*)$`).FindStringSubmatch(err.Error()); m != nil {
        fmt.Sprintf // inspect m[1] status, m[2] body
        _ = json.Unmarshal([]byte(m[2]), &apiErr)
        log.Printf("API %d: %s", apiErr.Error.Code, apiErr.Error.Message)
    }
}

When it happens

Trigger: resp.StatusCode < 200 || resp.StatusCode >= 300 after the executePipeline POST — e.g. 400 for a malformed MQL pipeline, 401/403 for bad or insufficient credentials, 404 for wrong project/database, 429 quota exceeded, 5xx server-side errors.

Common situations: Syntax errors in the MQL pipeline string; the service account lacking Firestore access or Firestore API not enabled on the project; querying a database id that doesn't exist; exceeding per-minute quotas; Google-side outages returning 500/503.

Related errors

• get_schema API error (status %d): %s
• unexpected status: %d
• status %d %s: %s
• request failed: %s, body: %s
• request failed with status %s: %s

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/e5f6c0cbf3c8348f. Report an issue: GitHub.