t8y2/dbx · error

remote file URI hosts are not supported: %s

Error message

remote file URI hosts are not supported: %s

What it means

normalizeLocalFilePath (config_file.go:353) accepts `file:` URIs only when the URI host is empty or 'localhost' (case-insensitive). A file URI with a remote hostname such as `file://fileserver/share/keytab` implies a network share rather than a local file and is rejected, since the driver must read the file from the local filesystem. Note that `file://host/path` puts the host part before the path, so this error often indicates a malformed file URI (one slash too few).

Source

Thrown at agents/drivers/cassandra-go/config_file.go:353

	}
	return nil
}

func normalizeLocalFilePath(raw string) (string, error) {
	value := strings.TrimSpace(raw)
	if value == "" {
		return "", nil
	}
	if strings.Contains(value, "://") || strings.HasPrefix(strings.ToLower(value), "file:") {
		parsed, err := url.Parse(value)
		if err != nil {
			return "", err
		}
		if parsed.Scheme != "file" {
			return "", fmt.Errorf("unsupported file URI scheme: %s", parsed.Scheme)
		}
		if parsed.Host != "" && !strings.EqualFold(parsed.Host, "localhost") {
			return "", fmt.Errorf("remote file URI hosts are not supported: %s", parsed.Host)
		}
		value, err = url.PathUnescape(parsed.Path)
		if err != nil {
			return "", err
		}
		if runtime.GOOS == "windows" && len(value) >= 3 && value[0] == '/' && value[2] == ':' {
			value = value[1:]
		}
	}
	return filepath.Clean(filepath.FromSlash(value)), nil
}

func hoconString(config *hocon.Config, path string) (string, bool, error) {
	if config.Get(path) == nil {
		return "", false, nil
	}
	value, err := config.GetStringE(path)
	if err != nil {

View on GitHub (pinned to c0390bff16)

Solutions

1. Use a three-slash file URI for local files: `file:///etc/cassandra/ca.pem` (empty host), not `file://host/path`.
2. Replace the remote-host URI with a genuine local path after copying the file onto the client machine.
3. On Windows UNC shares, use `file:////server/share/path` or the plain path `\\server\share\path` — the share is a remote host and may still need local staging.
4. 'localhost' as host is allowed (`file://localhost/path`), so fix hostnames to 'localhost' only if the file truly is local.

Example fix

// before
keytab := "file://fileserver.internal.example.com/kerberos/client.keytab"
// after (copy locally, then use local path)
exec.Command("scp", "fileserver:/kerberos/client.keytab", "/etc/krb5/client.keytab").Run()
keytab := "file:///etc/krb5/client.keytab"

func validateFileURIHost(raw string) error {
    v := strings.TrimSpace(raw)
    if v == "" || !(strings.Contains(v, "://") || strings.HasPrefix(strings.ToLower(v), "file:")) {
        return nil
    }
    u, err := url.Parse(v)
    if err != nil {
        return err
    }
    if u.Scheme == "file" && u.Host != "" && !strings.EqualFold(u.Host, "localhost") {
        return fmt.Errorf("file URI host %q not allowed; use file:///path (three slashes)", u.Host)
    }
    return nil
}

func isLocalFileURI(raw string) bool {
    u, err := url.Parse(strings.TrimSpace(raw))
    return err == nil && u.Scheme == "file" && (u.Host == "" || strings.EqualFold(u.Host, "localhost"))
}

if err := applyCassandraConfigFile(cfgPath); err != nil {
    if strings.Contains(err.Error(), "remote file URI hosts are not supported") {
        log.Fatalf("file URIs must be local: use file:///path with three slashes, and stage remote files locally")
    }
    return err
}

When it happens

Trigger: Passing `file://server/share/keytab`, `file://nas.mycompany.com/certs/ca.pem`, or a similarly malformed URI (e.g. `file:///etc/keytab` is fine, but `file://etc/keytab` yields host='etc') as a config path value to applyCassandraConfigFile or a kerberos path option.

Common situations: Windows UNC paths converted naively to file URIs (`file://server/share` instead of `file:////server/share`); dropping one slash from `file:///`; config templating that concatenates host + path into a file URI.

Related errors

• unsupported file URI scheme: %s
• Kerberos ticket cache path is empty
• invalid Kerberos credential cache path: %w
• invalid usekrb5 option: %w
• invalid disablepafxfast option: %w

AI-assisted analysis of t8y2/dbx@c0390bff16 (2026-09-05). Data as JSON: /api/errors/3dafe6716dd21c63. Report an issue: GitHub.