What causes "oracle connection refused: %s" in shadow1ng/fscan?

Check the embedded refusal text for the actual TNS- code and fix accordingly — usually the service name/SID is wrong: verify with lsnrctl status.

shadow1ng/fscan · error

oracle connection refused: %s

Error message

oracle connection refused: %s

What it means

When the Oracle listener refuses the connection, the raw refuse packet contains a text message. If no ORA-/TNS- code can be extracted from that text, the library wraps the raw text in this error; if a code is found it formats 'ORA-<code>: <msg>' instead. It signals the listener actively rejected the connection before authentication.

Source

Thrown at plugins/services/oracle_raw.go:1827

	msg := string(s.summary.errorMessage)
	if msg == "" {
		msg = fmt.Sprintf("ORA-%05d", s.summary.retCode)
	}
	return fmt.Errorf("%s", msg)
}

func oracleRefuseError(raw []byte) error {
	if len(raw) < 12 {
		return errors.New("oracle connection refused")
	}
	dataLen := int(binary.BigEndian.Uint16(raw[10:12]))
	if len(raw) < 12+dataLen {
		return errors.New("oracle connection refused")
	}
	msg := string(raw[12 : 12+dataLen])
	code := oracleExtractCode(msg)
	if code == 0 {
		return fmt.Errorf("oracle connection refused: %s", msg)
	}
	return fmt.Errorf("ORA-%05d: %s", code, msg)
}

func oracleExtractCode(msg string) int {
	upper := strings.ToUpper(msg)
	for _, marker := range []string{"ERR=", "CODE="} {
		idx := strings.Index(upper, marker)
		if idx < 0 {
			continue
		}
		idx += len(marker)
		for idx < len(upper) && (upper[idx] < '0' || upper[idx] > '9') {
			idx++
		}
		start := idx
		for idx < len(upper) && upper[idx] >= '0' && upper[idx] <= '9' {
			idx++

View on GitHub (pinned to 95cc12e753)

Solutions

Check the embedded refusal text for the actual TNS- code and fix accordingly — usually the service name/SID is wrong: verify with lsnrctl status.
If the database just started, wait for service registration or use a static listener registration (SID_LIST_LISTENER in listener.ora).
Confirm network ACLs / valid node checking on the listener allow the client host.

Example fix

// before
dsn := "oracle://user:pass@host:1521/ORCLW" // unknown service
// after
dsn := "oracle://user:pass@host:1521/ORCLPDB1" // service registered with listener

Defensive patterns

Strategy: retry

Try / catch

err := connect(ctx, dsn)
if err != nil && strings.Contains(err.Error(), "oracle connection refused") {
    // service may still be registering after a DB restart
    return backoffRetry(ctx, 5, 2*time.Second, func() error { return connect(ctx, dsn) })
}

Prevention

Verify service names with lsnrctl status before deploying config changes
Add startup health checks that wait for service registration after DB restarts
Register services statically in listener.ora to avoid registration races

When it happens

Trigger: oracleRefuseError(raw) receives a refuse packet where len(raw) >= 12+dataLen, extracts raw[12:12+dataLen], and oracleExtractCode finds no numeric code in the text — e.g. 'TNS-12514: TNS:listener does not currently know of service' variants without a parseable code, or free-form refusal text.

Common situations: Wrong SID/service name in the DSN (TNS-12514/12505); listener not registered with the instance after restart (ORA-12528); listener rejecting due to valid node checking or max connections; connecting before the DB finished starting up.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Connection failures: ECONNREFUSED, ECONNRESET, and friends — why connections get refused, reset, or dropped.

Related errors

AI-assisted analysis of shadow1ng/fscan@95cc12e753 (2026-09-06). Data as JSON: /api/errors/b26c6eb014045c31. Report an issue: GitHub.