apache/beam · error

file system scheme not registered for

Error message

file system scheme %q not registered for %q%s

What it means

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.

Solutions

1. Add the blank import for the scheme, e.g. import _ "github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/gcs"
2. Follow the import suggestion appended to the error message for well-known schemes
3. Verify the path's scheme is spelled correctly (gs:// not gcs://) — the scheme is parsed before lookup
4. For custom storage, register an implementation via filesystem.NewRegistry or implement filesystem.Interface and import it
5. Call filesystem.ValidateScheme early at pipeline construction to fail fast

Example fix

// before
import (
    "github.com/apache/beam/sdks/v2/go/pkg/beam"
    _ "github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/local"
)
// after
import (
    _ "github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/gcs"
    _ "github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/local"
)

import (
    _ "github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/gcs"
    _ "github.com/apache/beam/sdks/v2/go/pkg/beam/io/filesystem/local"
)

func ensureScheme(p string) error {
    u, err := url.Parse(p)
    if err != nil { return err }
    return filesystem.ValidateScheme(u.Scheme)
}

func hasRegisteredScheme(p string) bool {
    u, err := url.Parse(p)
    return err == nil && u.Scheme != "" && schemeImportExists(u.Scheme)
}

if err := filesystem.ValidateScheme(s); err != nil {
    return fmt.Errorf("unusable sink %q: %w", s, err)
}

When it happens

Trigger: 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"'.

Common situations: 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.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• failed to scan for artifacts to stage
• bad coder kind
• bad CoGBK
• bad combinefn
• bad decode

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/c7aef662b4c83d42. Report an issue: GitHub.

Appendix: source

Thrown at sdks/go/pkg/beam/io/filesystem/filesystem.go:72

	registry[scheme] = fs
}

// New returns a new Interface for the given file path's scheme.
func New(ctx context.Context, path string) (Interface, error) {
	scheme := getScheme(path)
	mkfs, ok := registry[scheme]
	if !ok {
		return nil, errorForMissingScheme(scheme, path)
	}
	return mkfs(ctx), nil
}

func errorForMissingScheme(scheme, path string) error {
	messageSuffix := ""
	if suggestedImportPath, ok := wellKnownSchemeImportPaths[scheme]; ok {
		messageSuffix = fmt.Sprintf(": Consider adding the following import to your program to register an implementation for %q:\n  import _ %q", scheme, suggestedImportPath)
	}
	return errors.Errorf("file system scheme %q not registered for %q%s", scheme, path, messageSuffix)
}

// Interface is a filesystem abstraction that allows beam io sources and sinks
// to use various underlying storage systems transparently.
type Interface interface {
	io.Closer

	// List expands a pattern to a list of filenames.
	// Returns nil if there are no matching files.
	List(ctx context.Context, glob string) ([]string, error)

	// OpenRead opens a file for reading.
	OpenRead(ctx context.Context, filename string) (io.ReadCloser, error)
	// OpenWrite opens a file for writing. If the file already exist, it will be
	// overwritten. The returned io.WriteCloser should be closed to commit the write.
	OpenWrite(ctx context.Context, filename string) (io.WriteCloser, error)
	// Size returns the size of a file in bytes.
	Size(ctx context.Context, filename string) (int64, error)

View on GitHub (pinned to 12126d8942)