provide only one connection method: 'tns_alias', 'connection

Error message

provide only one connection method: 'tns_alias', 'connection_string', or 'host'+'service_name'

What it means

If the Oracle config supplies more than one of tnsAlias, connectionString, or host+serviceName, validate rejects the ambiguity with this message, since the source cannot decide which connection method to use.

Source

Thrown at internal/sources/oracle/oracle.go:85

	hasWallet := strings.TrimSpace(c.WalletLocation) != ""

	connectionMethods := 0
	if hasTnsAlias {
		connectionMethods++
	}
	if hasConnStr {
		connectionMethods++
	}
	if hasHostService {
		connectionMethods++
	}

	if connectionMethods == 0 {
		return fmt.Errorf("must provide one of: 'tns_alias', 'connection_string', or both 'host' and 'service_name'")
	}

	if connectionMethods > 1 {
		return fmt.Errorf("provide only one connection method: 'tns_alias', 'connection_string', or 'host'+'service_name'")
	}

	if hasTnsAdmin && !c.UseOCI {
		return fmt.Errorf("`tnsAdmin` can only be used when `UseOCI` is true, or use `walletLocation` instead")
	}

	if hasWallet && c.UseOCI {
		return fmt.Errorf("when using an OCI driver, use `tnsAdmin` to specify credentials file location instead")
	}

	return nil
}

func (r Config) SourceConfigType() string {
	return SourceType
}

func (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {

View on GitHub (pinned to 8cc6e09de2)

Solutions

Keep exactly one connection method and delete the others
Prefer connectionString for full control, or host+serviceName for simple setups
Use tnsAlias only when a tnsAdmin wallet (OCI) or walletLocation supplies the TNS mapping

Example fix

// before
kind: oracle
tnsAlias: ORCL
connectionString: db.example.com:1521/ORCL
// after
kind: oracle
tnsAlias: ORCL
useOCI: true
tnsAdmin: /path/to/wallet

Defensive patterns

Strategy: validation

Validate before calling

func oneConnectionMethod(cfg map[string]any) bool {
    n := 0
    if _, ok := cfg["tnsAlias"]; ok { n++ }
    if _, ok := cfg["connectionString"]; ok { n++ }
    if _, ok := cfg["host"]; ok { n++ }
    return n <= 1
}

Prevention

Delete unused connection fields after switching methods
Avoid merging multiple Oracle config examples
Document which connection style your team standardizes on
Review diffs on source configs for stray fields

When it happens

Trigger: Setting both tnsAlias and connectionString, or a connectionString plus host/serviceName, in the same Oracle source config.

Common situations: Merging two example configs together; adding host/service overrides while a connectionString already exists; leftover fields from a previous connection style.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of googleapis/mcp-toolbox@8cc6e09de2 (2026-09-05). Data as JSON: /api/errors/c6f745f07f117cee. Report an issue: GitHub.