googleapis/mcp-toolbox · error

object %q: %d bytes exceeds %d byte limit: %w

Error message

object %q: %d bytes exceeds %d byte limit: %w

What it means

The remaining bytes of the opened range reader exceed the source's configured read limit (defaultMaxReadBytes), so the source aborts instead of buffering an oversized object into memory, wrapping ErrReadSizeLimitExceeded. This is an intentional guard, not a transport failure.

Source

Thrown at internal/sources/cloudstorage/cloudstorage.go:259

// narrow the range. Objects whose bytes are not valid UTF-8 are rejected
// with cloudstoragecommon.ErrBinaryContent.
//
// TODO: MCP tool results only carry text today, so we gate this tool on
// utf8.Valid. When the toolbox supports non-text MCP content (embedded
// resources, images, blobs), expand this to detect content type and return
// binary payloads natively.
func (s *Source) ReadObject(ctx context.Context, bucket, object string, offset, length int64) (map[string]any, error) {
	if err := s.validateBucket(bucket); err != nil {
		return nil, err
	}
	reader, err := s.client.Bucket(bucket).Object(object).NewRangeReader(ctx, offset, length)
	if err != nil {
		return nil, fmt.Errorf("failed to open object %q in bucket %q: %w", object, bucket, err)
	}
	defer reader.Close()

	if remain := reader.Remain(); remain > defaultMaxReadBytes {
		return nil, fmt.Errorf("object %q: %d bytes exceeds %d byte limit: %w",
			object, remain, defaultMaxReadBytes,
			cloudstoragecommon.ErrReadSizeLimitExceeded)
	}

	data, err := io.ReadAll(reader)
	if err != nil {
		return nil, fmt.Errorf("failed to read object %q in bucket %q: %w", object, bucket, err)
	}

	if !utf8.Valid(data) {
		return nil, fmt.Errorf("object %q in bucket %q: %w", object, bucket,
			cloudstoragecommon.ErrBinaryContent)
	}

	return map[string]any{
		"content":     string(data),
		"contentType": reader.Attrs.ContentType,
		"size":        len(data),

View on GitHub (pinned to 8cc6e09de2)

Solutions

1. Read only a byte range within the limit by passing a smaller offset/length to ReadObject.
2. Read the object in chunks by looping with offset += chunkSize until the whole object is consumed.
3. Export the object out-of-band (gsutil/gcloud storage or the GCS client directly) for files that should not be size-limited.
4. Increase defaultMaxReadBytes in the source configuration if the policy allows larger reads (mind memory cost).

Example fix

// before
res, err := source.ReadObject(ctx, "bkt", "big.json", 0, -1) // > defaultMaxReadBytes
// after
res, err := source.ReadObject(ctx, "bkt", "big.json", 0, 1<<20) // read first 1 MiB chunk

// read only within the limit, or chunk
const maxChunk = 1 << 20 // must stay <= defaultMaxReadBytes
if length < 0 || length > maxChunk {
    length = maxChunk
}
res, err := source.ReadObject(ctx, bucket, object, offset, length)

if errors.Is(err, cloudstoragecommon.ErrReadSizeLimitExceeded) {
    // switch to chunked/out-of-band read
}

When it happens

Trigger: ReadObject called (usually with length -1, i.e. whole object) on an object whose readable size is greater than defaultMaxReadBytes; also range reads whose requested length exceeds the limit.

Common situations: Reading large log/dataset/video files that were fine when the limit was chosen but have grown; users pointing the tool at a multi-GB object expecting a full text read; raising the range length beyond the cap.

Related errors

• failed to open object %q in bucket %q: %w
• failed to read object %q in bucket %q: %w
• failed to list objects in bucket %q: %w
• object %q in bucket %q: %w
• failed to list buckets in project %q: %w

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