{"record":{"id":"30705932caf07ede","repo":"googleapis/mcp-toolbox","slug":"unable-to-connect-successfully-w-307059","errorCode":null,"errorMessage":"unable to connect successfully: %w","messagePattern":"unable to connect successfully: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/sources/firebird/firebird.go","lineNumber":71,"sourceCode":"\tUser     string `yaml:\"user\" validate:\"required\"`\n\tPassword string `yaml:\"password\" validate:\"required\"`\n\tDatabase string `yaml:\"database\" validate:\"required\"`\n}\n\nfunc (r Config) SourceConfigType() string {\n\treturn SourceType\n}\n\nfunc (r Config) Initialize(ctx context.Context, tracer trace.Tracer) (sources.Source, error) {\n\tpool, err := initFirebirdConnectionPool(ctx, tracer, r.Name, r.Host, r.Port, r.User, r.Password, r.Database)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"unable to create pool: %w\", err)\n\t}\n\n\terr = pool.PingContext(ctx)\n\tif err != nil {\n\t\tpool.Close()\n\t\treturn nil, fmt.Errorf(\"unable to connect successfully: %w\", err)\n\t}\n\n\ts := &Source{\n\t\tConfig: r,\n\t\tDb:     pool,\n\t}\n\treturn s, nil\n}\n\nvar _ sources.Source = &Source{}\n\ntype Source struct {\n\tConfig\n\tDb *sql.DB\n}\n\nfunc (s *Source) IsReadOnly() bool {\n\treturn false","sourceCodeStart":53,"sourceCodeEnd":89,"githubUrl":"https://github.com/googleapis/mcp-toolbox/blob/8cc6e09de2ad7b8bffc77751799585a1401a48eb/internal/sources/firebird/firebird.go#L53-L89","documentation":"Wrapped when pool.PingContext fails after the pool was opened successfully — meaning the DSN parsed but an actual round-trip to the Firebird server failed (unreachable host, wrong credentials, database file not found). Initialize closes the pool before returning this error.","triggerScenarios":"Initialize called and PingContext returns: server down/firewalled, wrong user/password, database path does not exist on the server, or ctx deadline exceeded before the handshake completes.","commonSituations":"Firebird service not running on port 3050; credentials rotated without updating config; relative vs absolute .fdb path confusion between client and server; Docker network isolation; slow embedded startup exceeding context deadline.","solutions":["Verify the Firebird server is listening (telnet/nc host 3050)","Validate credentials with isql or flamerobin using the same user/password/database","Check the database file path exists as seen from the SERVER, not the client","Increase the context timeout if the server is slow to accept connections"],"exampleFix":"// before\nerr = pool.PingContext(ctx)\nif err != nil {\n    pool.Close()\n    return nil, fmt.Errorf(\"unable to connect successfully: %w\", err)\n}\n// after\nctxPing, cancel := context.WithTimeout(ctx, 10*time.Second)\ndefer cancel()\nif err := pool.PingContext(ctxPing); err != nil {\n    pool.Close()\n    return nil, fmt.Errorf(\"unable to connect successfully (host=%s:%s): %w\", r.Host, r.Port, err)\n}","handlingStrategy":"retry","validationCode":"// Check TCP reachability before Initialize\nconn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, port), 5*time.Second)\nif err != nil { return fmt.Errorf(\"firebird server unreachable: %w\", err) }\nconn.Close()","typeGuard":"func isAuthFailure(err error) bool {\n    s := err.Error()\n    return strings.Contains(s, \"Your user name and password are not defined\") || strings.Contains(s, \"login\")\n}","tryCatchPattern":"if err := pool.PingContext(ctx); err != nil {\n    pool.Close()\n    if isAuthFailure(err) {\n        return nil, fmt.Errorf(\"firebird credentials rejected: %w\", err)\n    }\n    // transient network errors may be retried with backoff\n    return nil, fmt.Errorf(\"unable to connect successfully: %w\", err)\n}","preventionTips":["Health-check host:port reachability as a preflight step","Rotate credentials via secret manager and verify before deploys","Use absolute server-side .fdb paths and confirm they exist","Set generous Ping timeouts for slow/embedded Firebird startup"],"tags":["firebird","connectivity","ping","authentication"],"backgroundTag":"connection-refused","analyzedSha":"8cc6e09de2ad7b8bffc77751799585a1401a48eb","analyzedAt":"2026-09-05T01:10:36.887Z","contentChangedAt":"2026-09-05T01:10:36.887Z","schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}