{"record":{"id":"8412cf27de8e4c4d","repo":"apache/hadoop","slug":"gcs-path-supports-only-s-scheme-instead-got","errorCode":null,"errorMessage":"GCS path supports only '%s' scheme, instead got '%s' from '%s'.","messagePattern":"GCS path supports only '(.+?)' scheme, instead got '(.+?)' from '(.+?)'\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/StorageResourceId.java","lineNumber":311,"sourceCode":"    return fromUriPath(path, allowEmptyObjectName, UNKNOWN_GENERATION_ID);\n  }\n\n  /**\n   * Validates the given URI and if valid, returns the associated StorageResourceId.\n   *\n   * @param path                 The GCS URI to validate.\n   * @param allowEmptyObjectName If true, a missing object name is not considered invalid.\n   * @param generationId         The generationId to be used with precondition checks when\n   *                             using this\n   * @return a StorageResourceId that may be the GCS root, a Bucket, or a StorageObject.\n   */\n  static StorageResourceId fromUriPath(URI path, boolean allowEmptyObjectName,\n      long generationId) {\n    LOG.trace(\"fromUriPath('{}', {})\", path, allowEmptyObjectName);\n    checkNotNull(path);\n\n    if (!SCHEME.equals(path.getScheme())) {\n      throw new IllegalArgumentException(\n          String.format(\"GCS path supports only '%s' scheme, instead got '%s' from '%s'.\", SCHEME,\n              path.getScheme(), path));\n    }\n\n    if (path.equals(GoogleCloudStorageFileSystem.GCSROOT)) {\n      return ROOT;\n    }\n\n    String bucketName = StringPaths.validateBucketName(path.getAuthority());\n    // Note that we're using getPath here instead of rawPath, etc. This is because it is assumed\n    // that the path was properly encoded in getPath (or another similar method):\n    String objectName = StringPaths.validateObjectName(path.getPath(), allowEmptyObjectName);\n\n    return isNullOrEmpty(objectName) ?\n        new StorageResourceId(bucketName, generationId) :\n        new StorageResourceId(bucketName, objectName, generationId);\n  }\n","sourceCodeStart":293,"sourceCodeEnd":329,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-cloud-storage-project/hadoop-gcp/src/main/java/org/apache/hadoop/fs/gs/StorageResourceId.java#L293-L329","documentation":"StorageResourceId.fromUriPath requires the URI scheme to be exactly 'gs' (the SCHEME constant, case-sensitive); anything else (hdfs, s3a, file, an odd-case 'GS') throws IllegalArgumentException showing the offending scheme and full URI. This is the connector's lowest-level URI-to-resource parser used by both GoogleCloudStorageFileSystem and the Hadoop layer.","triggerScenarios":"fromUriPath(URI.create(\"hdfs://bucket/obj\")); passing Path.toUri() values obtained from another FileSystem; uppercase scheme variants like 'GS://bucket/obj'; URIs built by string concatenation with the wrong prefix.","commonSituations":"Connector code receiving paths from external systems; tests constructing generic URIs; scheme normalization bugs where the scheme is dropped or re-cased; mixed-store utility code reusing one URI builder.","solutions":["Normalize the URI scheme to lowercase 'gs' before calling fromUriPath.","Route non-gs paths to their own FileSystem instead of the GCS connector.","Where the scheme is untrusted, build StorageResourceId from bucket/object name strings directly instead of parsing a URI."],"exampleFix":"// before\nStorageResourceId id = StorageResourceId.fromUriPath(URI.create(\"s3a://bucket/obj\"), false);\n// -> IllegalArgumentException: GCS path supports only 'gs' scheme\n\n// after\nURI gcsUri = URI.create(\"gs://bucket/obj\");\nStorageResourceId id = StorageResourceId.fromUriPath(gcsUri, false);","handlingStrategy":"validation","validationCode":"URI u = raw.toUri();\nif (!\"gs\".equals(u.getScheme())) {\n  u = URI.create(\"gs://\" + u.getAuthority() + u.getPath()); // normalize before parsing\n}\nStorageResourceId id = StorageResourceId.fromUriPath(u, false);","typeGuard":"static boolean isGcsUri(URI u) {\n  return u != null && \"gs\".equals(u.getScheme()); // scheme match is case-sensitive\n}","tryCatchPattern":"catch IllegalArgumentException with message startsWith(\"GCS path supports only\") - fix or normalize the scheme at the call site; the message shows the offending URI.","preventionTips":["Validate scheme == 'gs' (lowercase, exact) before passing URIs to fromUriPath.","Keep one URI builder per backend store; never reuse builders across schemes."],"tags":["uri","gcs","hadoop","scheme","validation"],"backgroundTag":"filesystem-scheme-mismatch","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}