{"record":{"id":"c7aef662b4c83d42","repo":"apache/beam","slug":"file-system-scheme-q-not-registered-for-q-s","errorCode":null,"errorMessage":"file system scheme %q not registered for %q%s","messagePattern":"file system scheme %q not registered for %q(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"sdks/go/pkg/beam/io/filesystem/filesystem.go","lineNumber":72,"sourceCode":"\tregistry[scheme] = fs\n}\n\n// New returns a new Interface for the given file path's scheme.\nfunc New(ctx context.Context, path string) (Interface, error) {\n\tscheme := getScheme(path)\n\tmkfs, ok := registry[scheme]\n\tif !ok {\n\t\treturn nil, errorForMissingScheme(scheme, path)\n\t}\n\treturn mkfs(ctx), nil\n}\n\nfunc errorForMissingScheme(scheme, path string) error {\n\tmessageSuffix := \"\"\n\tif suggestedImportPath, ok := wellKnownSchemeImportPaths[scheme]; ok {\n\t\tmessageSuffix = fmt.Sprintf(\": Consider adding the following import to your program to register an implementation for %q:\\n  import _ %q\", scheme, suggestedImportPath)\n\t}\n\treturn errors.Errorf(\"file system scheme %q not registered for %q%s\", scheme, path, messageSuffix)\n}\n\n// Interface is a filesystem abstraction that allows beam io sources and sinks\n// to use various underlying storage systems transparently.\ntype Interface interface {\n\tio.Closer\n\n\t// List expands a pattern to a list of filenames.\n\t// Returns nil if there are no matching files.\n\tList(ctx context.Context, glob string) ([]string, error)\n\n\t// OpenRead opens a file for reading.\n\tOpenRead(ctx context.Context, filename string) (io.ReadCloser, error)\n\t// OpenWrite opens a file for writing. If the file already exist, it will be\n\t// overwritten. The returned io.WriteCloser should be closed to commit the write.\n\tOpenWrite(ctx context.Context, filename string) (io.WriteCloser, error)\n\t// Size returns the size of a file in bytes.\n\tSize(ctx context.Context, filename string) (int64, error)","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/go/pkg/beam/io/filesystem/filesystem.go#L54-L90","documentation":"Beam's Go filesystem layer routes file paths to registered storage implementations by URI scheme (gs://, s3://, file://, etc.). errorForMissingScheme produces this error when New() or ValidateScheme() is given a path whose scheme has no registered filesystem. For well-known schemes the message suggests the blank import that registers the implementation.","triggerScenarios":"Calling filesystem.New(s) or filesystem.ValidateScheme(s) with a path whose scheme (e.g. gs) was never imported/registered — e.g. missing 'import _ \"github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/gcs\"'.","commonSituations":"Refactoring removed the blank import of a filesystem package; running on a new sink/source with s3:// or azfs:// but only the GCS or local driver registered; using a custom scheme with no driver at all.","solutions":["Add the blank import for the scheme, e.g. import _ \"github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/gcs\"","Follow the import suggestion appended to the error message for well-known schemes","Verify the path's scheme is spelled correctly (gs:// not gcs://) — the scheme is parsed before lookup","For custom storage, register an implementation via filesystem.NewRegistry or implement filesystem.Interface and import it","Call filesystem.ValidateScheme early at pipeline construction to fail fast"],"exampleFix":"// before\nimport (\n    \"github.com/apache/beam/sdks/v2/go/pkg/beam\"\n    _ \"github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/local\"\n)\n// after\nimport (\n    _ \"github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/gcs\"\n    _ \"github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/local\"\n)","handlingStrategy":"validation","validationCode":"import (\n    _ \"github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/gcs\"\n    _ \"github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/local\"\n)\n\nfunc ensureScheme(p string) error {\n    u, err := url.Parse(p)\n    if err != nil { return err }\n    return filesystem.ValidateScheme(u.Scheme)\n}","typeGuard":"func hasRegisteredScheme(p string) bool {\n    u, err := url.Parse(p)\n    return err == nil && u.Scheme != \"\" && schemeImportExists(u.Scheme)\n}","tryCatchPattern":"if err := filesystem.ValidateScheme(s); err != nil {\n    return fmt.Errorf(\"unusable sink %q: %w\", s, err)\n}","preventionTips":["Always blank-import every filesystem driver you use (gcs, s3, local)","Keep imports in a central setup file so refactors don't drop them","Validate schemes at pipeline-construction time, not at runtime","Match scheme spelling exactly to the driver (gs:// for GCS)"],"tags":["go","beam","filesystem","missing-import"],"backgroundTag":"unsupported-operation","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"}