{"record":{"id":"1759ac31e45a7e9e","repo":"googleapis/mcp-toolbox","slug":"errreadsizelimitexceeded","errorCode":"ErrReadSizeLimitExceeded","errorMessage":"cloud storage read size limit exceeded","messagePattern":"cloud storage read size limit exceeded","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/tools/cloudstorage/cloudstoragecommon/errors.go","lineNumber":34,"sourceCode":"// tool implementations, chiefly error classification.\npackage cloudstoragecommon\n\nimport (\n\t\"context\"\n\t\"errors\"\n\t\"net/http\"\n\t\"os\"\n\n\t\"cloud.google.com/go/storage\"\n\t\"github.com/googleapis/mcp-toolbox/internal/util\"\n\t\"google.golang.org/api/googleapi\"\n)\n\n// ErrReadSizeLimitExceeded is returned by the source when an object/range\n// would exceed the source's configured byte limit. ProcessGCSError maps this\n// to an Agent error because the LLM can fix the call by narrowing the 'range'\n// parameter.\nvar ErrReadSizeLimitExceeded = errors.New(\"cloud storage read size limit exceeded\")\n\n// ErrBinaryContent is returned by the source when an object's bytes are not\n// valid UTF-8. The MCP tool result channel only carries text today, so binary\n// payloads cannot be faithfully round-tripped; ProcessGCSError maps this to an\n// Agent error so the LLM knows to stop asking for this object.\n//\n// TODO: when the toolbox supports non-text MCP content (embedded resources,\n// images, blobs), remove this guard and return binary payloads directly.\nvar ErrBinaryContent = errors.New(\"cloud storage object is not valid UTF-8 text\")\n\n// ErrDestinationExists is returned by the download_object source method when\n// the local destination file already exists and overwrite is false.\n// ProcessGCSError maps this to an Agent error so the LLM can retry the call\n// with overwrite=true.\nvar ErrDestinationExists = errors.New(\"download destination already exists\")\n\n// ProcessGCSError classifies an error from the Cloud Storage Go client into\n// either an Agent Error (the LLM can self-correct by changing its input — bad","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/tools/cloudstorage/cloudstoragecommon/errors.go#L16-L52","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Narrow the 'range' parameter to fetch a smaller byte window that fits under the limit, and paginate with subsequent calls.","Check the object's size (e.g. via list_objects metadata) before reading and plan ranges accordingly.","If legitimate larger reads are needed, raise the source's configured byte limit in the toolbox config and restart."],"exampleFix":"// before: read whole object\n{\"tool\": \"read_object\", \"args\": {\"bucket\": \"logs\", \"object\": \"app-2026.log\"}}\n// after: read in bounded chunks\n{\"tool\": \"read_object\", \"args\": {\"bucket\": \"logs\", \"object\": \"app-2026.log\", \"range\": \"0-1048575\"}}","handlingStrategy":"retry","validationCode":"if obj.Size > defaultMaxReadBytes {\n    // plan ranged reads instead of a full read\n    for start := int64(0); start < obj.Size; start += chunkSize { /* read_object with range */ }\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, cloudstoragecommon.ErrReadSizeLimitExceeded) {\n    // split the request: retry with a narrower 'range' parameter\n}","preventionTips":["Check object size metadata before read_object and chunk large objects with 'range'.","Wrap reads in logic that retries with halved ranges when this error occurs.","Document the source's byte limit where the agent can see it."],"tags":["gcp","cloud-storage","limit-exceeded","agent-correctable"],"backgroundTag":"read-size-limit-exceeded","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}