googleapis/mcp-toolbox · error

ErrReadSizeLimitExceeded

ErrReadSizeLimitExceeded

Error message

cloud storage read size limit exceeded

What it means

ErrReadSizeLimitExceeded is returned by the Cloud Storage source's ReadObject when an object or the requested byte range exceeds the source's configured read byte limit (defaultMaxReadBytes). It is wrapped so ProcessGCSError can classify it as an Agent error: the LLM caller can self-correct by narrowing the 'range' parameter instead of the operator changing infrastructure. It signals a policy cap, not a storage failure.

Source

Thrown at internal/tools/cloudstorage/cloudstoragecommon/errors.go:34

// tool implementations, chiefly error classification.
package cloudstoragecommon

import (
	"context"
	"errors"
	"net/http"
	"os"

	"cloud.google.com/go/storage"
	"github.com/googleapis/mcp-toolbox/internal/util"
	"google.golang.org/api/googleapi"
)

// ErrReadSizeLimitExceeded is returned by the source when an object/range
// would exceed the source's configured byte limit. ProcessGCSError maps this
// to an Agent error because the LLM can fix the call by narrowing the 'range'
// parameter.
var ErrReadSizeLimitExceeded = errors.New("cloud storage read size limit exceeded")

// ErrBinaryContent is returned by the source when an object's bytes are not
// valid UTF-8. The MCP tool result channel only carries text today, so binary
// payloads cannot be faithfully round-tripped; ProcessGCSError maps this to an
// Agent error so the LLM knows to stop asking for this object.
//
// TODO: when the toolbox supports non-text MCP content (embedded resources,
// images, blobs), remove this guard and return binary payloads directly.
var ErrBinaryContent = errors.New("cloud storage object is not valid UTF-8 text")

// ErrDestinationExists is returned by the download_object source method when
// the local destination file already exists and overwrite is false.
// ProcessGCSError maps this to an Agent error so the LLM can retry the call
// with overwrite=true.
var ErrDestinationExists = errors.New("download destination already exists")

// ProcessGCSError classifies an error from the Cloud Storage Go client into
// either an Agent Error (the LLM can self-correct by changing its input — bad

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Narrow the 'range' parameter to fetch a smaller byte window that fits under the limit, and paginate with subsequent calls.
2. Check the object's size (e.g. via list_objects metadata) before reading and plan ranges accordingly.
3. If legitimate larger reads are needed, raise the source's configured byte limit in the toolbox config and restart.

Example fix

// before: read whole object
{"tool": "read_object", "args": {"bucket": "logs", "object": "app-2026.log"}}
// after: read in bounded chunks
{"tool": "read_object", "args": {"bucket": "logs", "object": "app-2026.log", "range": "0-1048575"}}

if obj.Size > defaultMaxReadBytes {
    // plan ranged reads instead of a full read
    for start := int64(0); start < obj.Size; start += chunkSize { /* read_object with range */ }
}

if errors.Is(err, cloudstoragecommon.ErrReadSizeLimitExceeded) {
    // split the request: retry with a narrower 'range' parameter
}

When it happens

Trigger: Calling the read_object tool/source method on a GCS object whose total size, or whose requested 'range' span, exceeds the configured max read bytes (default defaultMaxReadBytes). Happens when reading a large object with no range, or with a range whose remaining bytes (remain) still exceed the cap.

Common situations: Reading a large log, CSV, or JSON export from a bucket without limiting the range; misjudging object size before calling; a configured source byte limit lower than expected after a config/version change.

Related errors

• ErrBinaryContent
• ErrDestinationExists
• unable to create client: %w
• error creating AlloyDB instance: %w
• error creating AlloyDB user: %w

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