apache/beam · error

errorForMissingScheme(scheme, path)

Error message

errorForMissingScheme(scheme, path)

What it means

ValidateScheme panics with errorForMissingScheme when the path's URI scheme (e.g. s3://, gs://, file://) has no filesystem registered in Beam's filesystem registry. Beam can only route I/O to schemes registered via filesystem.NewSchemeRegistrar or built-in init() registration. This fail-fast prevents an obscure nil filesystem later in the pipeline.

Solutions

1. Blank-import the filesystem package for the scheme: _ ".../io/filesystem/filesystem/s3"
2. Verify the scheme in your path is correct (lowercase, no typos)
3. Register a custom filesystem with filesystem.NewSchemeRegistrar if using a custom backend
4. Print getScheme(path) equivalent to confirm what scheme Beam extracted

Example fix

// before
import (
    _ "github.com/apache/beam/sdks/go/pkg/beam/io/filesystem/gcs"
)
filesystem.Read(ctx, s, "s3://bucket/key")
// after
import (
    _ "github.com/apache/beam/sdks/go/pkg/beam/io/filesystem/gcs"
    _ "github.com/apache/beam/sdks/go/pkg/beam/io/filesystem/s3"
)
filesystem.Read(ctx, s, "s3://bucket/key")

u, err := url.Parse(path)
if err != nil || u.Scheme == "" { return fmt.Errorf("path %q has no scheme", path) }
// ensure the driver is imported for the scheme

defer func() { if r := recover(); r != nil { log.Fatalf("unsupported scheme: %v", r) } }()

When it happens

Trigger: Calling Read/Write/MatchFiles/TestFilesystem with a path whose scheme was never registered: using s3:// without importing the s3 package, a typo like httpx://, or an empty scheme from a malformed path like "/no-scheme" when no default filesystem applies.

Common situations: Forgetting to blank-import _ "github.com/apache/beam/sdks/go/pkg/beam/io/filesystem/s3" in a custom pipeline; switching storage backends without importing the new driver; path parsing producing an unexpected scheme.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• empty file glob provided
• scheme already registered
• AfterProcessingTime trigger set without a delay or…
• At least one subtrigger required for composite triggers.
• attempted to add namespace to missing coder id

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

Appendix: source

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

	Rename(ctx context.Context, oldpath, newpath string) error
}

func getScheme(path string) string {
	if index := strings.Index(path, "://"); index > 0 {
		return path[:index]
	}
	return "default"
}

// ValidateScheme panics if the given path's scheme does not have a
// corresponding file system registered.
func ValidateScheme(path string) {
	if strings.TrimSpace(path) == "" {
		panic("empty file glob provided")
	}
	scheme := getScheme(path)
	if _, ok := registry[scheme]; !ok {
		panic(errorForMissingScheme(scheme, path))
	}
}

View on GitHub (pinned to 12126d8942)