{"record":{"id":"b1b2f1ede20e7011","repo":"apache/hadoop","slug":"s-s","errorCode":null,"errorMessage":"%s : %s","messagePattern":"%s : %s","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-cos/src/main/java/org/apache/hadoop/fs/cosn/CosNativeFileSystemStore.java","lineNumber":659,"sourceCode":"      handleException(new Exception(errMsg), srcKey);\n    }\n  }\n\n  @Override\n  public void purge(String prefix) throws IOException {\n    throw new IOException(\"purge not supported\");\n  }\n\n  @Override\n  public void dump() throws IOException {\n    throw new IOException(\"dump not supported\");\n  }\n\n  // process Exception and print detail\n  private void handleException(Exception e, String key) throws IOException {\n    String cosPath = CosNFileSystem.SCHEME + \"://\" + bucketName + key;\n    String exceptInfo = String.format(\"%s : %s\", cosPath, e.toString());\n    throw new IOException(exceptInfo);\n  }\n\n  @Override\n  public long getFileLength(String key) throws IOException {\n    LOG.debug(\"Get file length. COS key: {}\", key);\n    GetObjectMetadataRequest getObjectMetadataRequest =\n        new GetObjectMetadataRequest(bucketName, key);\n    try {\n      ObjectMetadata objectMetadata =\n          (ObjectMetadata) callCOSClientWithRetry(getObjectMetadataRequest);\n      return objectMetadata.getContentLength();\n    } catch (Exception e) {\n      String errMsg = String.format(\"Getting file length occurs an exception.\" +\n              \"COS key: %s, exception: %s\", key,\n          e.toString());\n      LOG.error(errMsg);\n      handleException(new Exception(errMsg), key);\n      return 0; // never will get here","sourceCodeStart":641,"sourceCodeEnd":677,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-cos/src/main/java/org/apache/hadoop/fs/cosn/CosNativeFileSystemStore.java#L641-L677","documentation":"handleException is the central error wrapper of CosNativeFileSystemStore: it takes the failing COS key, builds the fully qualified cosn://bucket+key URI, and rethrows the original exception text as a new IOException formatted \"%s : %s\" (uri : cause). Seeing this message means an underlying COS operation (metadata fetch, read, delete, upload part) failed and its cause was flattened into the message text. The real root cause (NoSuchKey, AccessDenied, throttling, timeout) must be read from the portion after the ' : ' separator.","triggerScenarios":"Any store operation routed through handleException fails on the backend, e.g. getFileLength(key) when the object does not exist or metadata HEAD fails, copy/read failures inside the block-based input/output streams, or object deletes that error out. The wrapper fires only on the catch paths that call it, converting Exception to IOException with path context.","commonSituations":"Reading a stale/cosn path after the object was deleted or renamed; wrong bucket or key prefix in fs.cosn configuration; credentials without permission on the bucket; transient Tencent COS network errors surfacing mid-read.","solutions":["Parse the suffix after the first ' : ' in the message to identify the real cause, then fix that (missing object, permissions, network)","Verify the object exists with fs.exists()/getFileStatus before reading the failing path","Check the fs.cosn.userinfo.appid / bucket credentials have GetObject/HeadObject rights on that key","For transient causes seen in the suffix, retry the operation — the store only retries SDK-level 5xx, not every path"],"exampleFix":"// before\nlong len = fs.getFileStatus(new Path(\"cosn://bucket/missing-key\")).getLen();\n// -> IOException \"cosn://bucket/missing-key : com.qcloud.cos.exception.CosServiceException: ... NoSuchKey\"\n\n// after\nPath p = new Path(\"cosn://bucket/missing-key\");\nif (!fs.exists(p)) {\n  throw new FileNotFoundException(p.toString());\n}\nlong len = fs.getFileStatus(p).getLen();","handlingStrategy":"try-catch","validationCode":"// Avoid the common NoSuchKey path before reading\nPath p = new Path(\"cosn://bucket/key\");\nif (!fs.exists(p)) {\n  throw new FileNotFoundException(p.toString());\n}","typeGuard":null,"tryCatchPattern":"try {\n  long len = store.getFileLength(key);\n} catch (IOException e) {\n  // message is \"cosn://bucket/key : <cause>\" — split on first \" : \" to recover the cause text\n  String cause = e.getMessage().substring(e.getMessage().indexOf(\" : \") + 3);\n  if (cause.contains(\"NoSuchKey\")) { /* treat as missing */ }\n  else { throw e; }\n}","preventionTips":["Always log the full IOException text — the real cause is embedded after the cosn:// URI prefix","Verify paths with exists()/getFileStatus() before reads","Ensure the service account/key has HeadObject/GetObject rights on the bucket"],"tags":["cosn","hadoop-cos","error-wrapping","object-storage","ioexception"],"backgroundTag":"object-storage-request-failed","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}