{"record":{"id":"d405b576f36941a3","repo":"apache/beam","slug":"error-when-parsing-input-schema-file","errorCode":null,"errorMessage":"Error when parsing input schema file: ","messagePattern":"Error when parsing input schema file: ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"sdks/java/io/file-schema-transform/src/main/java/org/apache/beam/sdk/io/fileschematransform/FileReadSchemaTransformProvider.java","lineNumber":222,"sourceCode":"          return schema;\n        }\n        checkArgument(\n            !result.metadata().isEmpty(),\n            \"Failed to match any files for the input schema file path.\");\n        List<ResourceId> resource =\n            result.metadata().stream()\n                .map(MatchResult.Metadata::resourceId)\n                .collect(Collectors.toList());\n\n        checkArgument(\n            resource.size() == 1,\n            \"Expected exactly 1 schema file, but got \" + resource.size() + \" files.\");\n\n        ReadableByteChannel byteChannel = FileSystems.open(resource.get(0));\n        Reader reader = Channels.newReader(byteChannel, UTF_8.name());\n        return CharStreams.toString(reader);\n      } catch (IOException e) {\n        throw new RuntimeException(\"Error when parsing input schema file: \", e);\n      }\n    }\n\n    private FileReadSchemaTransformFormatProvider getProvider() {\n      String format = configuration.getFormat();\n      Map<String, FileReadSchemaTransformFormatProvider> providers =\n          Providers.loadProviders(FileReadSchemaTransformFormatProvider.class);\n      checkArgument(\n          providers.containsKey(format),\n          String.format(\n              \"Received unsupported file format: %s. Supported formats are %s\",\n              format, providers.keySet()));\n\n      Optional<FileReadSchemaTransformFormatProvider> provider =\n          Optional.ofNullable(providers.get(format));\n      checkState(provider.isPresent());\n      return provider.get();\n    }","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/io/file-schema-transform/src/main/java/org/apache/beam/sdk/io/fileschematransform/FileReadSchemaTransformProvider.java#L204-L240","documentation":"FileReadSchemaTransformProvider.resolveSchemaStringOrFilePath loads the schema from either the inline schema string or a schema file path via FileSystems. When reading the schema file raises an IOException (file missing, unreadable, network filesystem failure), it is wrapped in a RuntimeException with this message. It means the transform could not obtain the row schema needed to parse input files.","triggerScenarios":"FileReadSchemaTransformConfiguration with schema set to a file path (e.g. 'gs://bucket/schema.json') where the path doesn't match any file, matches multiple files, or FileSystems.open fails (permission/network error).","commonSituations":"Wrong GCS/S3/local path; bucket permissions for the pipeline service account; schema file deleted between config authoring and run; ambiguous glob matching more than one file (fails earlier with its own message).","solutions":["Verify the schema file path/URI is correct and the file exists","Check read permissions for the pipeline runner's service account on the file/bucket","Test FileSystems.open with the same URI in a small job or via gsutil/s3 cmd","If the schema is small, inline it in the configuration's schema string instead of a path","Confirm the matching filesystem is registered (gcs-connector/hadoop-fs dependencies)"],"exampleFix":"// before\n.withSchema(\"gs://my-bucket/schemas/missing.json\")\n// after\n.withSchema(\"gs://my-bucket/schemas/user.json\") // or inline: \"{\\\"fields\\\":[...]}\"","handlingStrategy":"validation","validationCode":"MatchResult res = FileSystems.match(schemaPath);\nif (res.metadata().size() != 1)\n  throw new IllegalArgumentException(\"Expected exactly 1 schema file at \" + schemaPath\n      + \", got \" + res.metadata().size());","typeGuard":null,"tryCatchPattern":"try {\n  apply(FileReadSchemaTransformProvider...);\n} catch (RuntimeException e) {\n  if (e.getMessage().startsWith(\"Error when parsing input schema file\"))\n    LOG.error(\"Check schema path/permissions: {}\", e.getCause());\n  throw e;\n}","preventionTips":["Assert the schema file exists with FileSystems.match before running the pipeline","Inline small schemas in the config string to avoid file I/O entirely","Grant the runner service account read access to the schema location"],"tags":["java","beam","schema","file-io"],"backgroundTag":"file-read-failed","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}