googleapis/mcp-toolbox · error

get_schema API error (status %d): %s

Error message

get_schema API error (status %d): %s

What it means

After POSTing the get_schema pipeline request to the Firestore executePipeline REST endpoint, getSchemaFromPipeline checks the HTTP status code. Any non-2xx response causes this error, embedding the status code and the raw response body so the server-side reason (auth failure, bad request, unsupported stage) is visible.

Source

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

	}
	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 CollectionSchema{}, err
	}
	defer resp.Body.Close()

	respBody, err := io.ReadAll(resp.Body)
	if err != nil {
		return CollectionSchema{}, err
	}

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

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

	fields := parseFieldsFromPipelineResponse(rawResult)
	return CollectionSchema{
		Collection: collection,
		Fields:     fields,
	}, nil
}

func parseFieldsFromPipelineResponse(raw any) []FieldSchema {
	var fields []FieldSchema
	switch data := raw.(type) {
	case []any:

View on GitHub (pinned to 8cc6e09de2)

Solutions

  1. Read the response body in the error message — it contains Google's API error reason (e.g. 'get_schema stage is not supported').
  2. Verify project ID and database ID in the source config match an existing Firestore database.
  3. Confirm the credential has datastore access; re-authenticate with gcloud auth application-default login.
  4. If the API/stage is unsupported, fall back to document sampling (GetSchema's fallback path) or upgrade the Firestore database/runtime.
Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-check the API endpoint reachability and auth token before schema discovery
_, err := google.DefaultClient(ctx, "https://www.googleapis.com/auth/datastore")
if err != nil {
    return fmt.Errorf("ADC not available, get_schema call would 401/403: %w", err)
}

Type guard

func isGetSchemaHTTPError(err error) (statusCode int, body string, ok bool) {
    if err == nil || !strings.Contains(err.Error(), "get_schema API error") {
        return 0, "", false
    }
    var n int
    if _, scanErr := fmt.Sscanf(err.Error(), "get_schema API error (status %d):", &n); scanErr != nil {
        return 0, err.Error(), true
    }
    return n, err.Error(), true
}

Try / catch

schema, err := getSchemaFromPipeline(ctx, coll)
if err != nil {
    var gsErr statusCodeError
    if errors.As(err, &gsErr) {
        switch {
        case gsErr.code == 401 || gsErr.code == 403:
            // refresh credentials / fix IAM and retry
        case gsErr.code == 400 || gsErr.code == 501:
            // get_schema stage unsupported: fall back to document sampling
        case gsErr.code >= 500:
            // retry with exponential backoff
        }
    }
    return err
}

Prevention

When it happens

Trigger: The Firestore executePipeline API returns 4xx/5xx: invalid or missing OAuth token (401/403), malformed structuredPipeline payload (400), get_schema stage not enabled for the database (400/501), project/database not found (404), or server errors (5xx).

Common situations: Running against a Firestore database (especially Firestore in Native mode on older versions or emulator) that doesn't support pipeline get_schema stages; wrong project ID or database ID in the source config; expired/insufficient credentials; regional restrictions.

Related errors

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