useEmulator(withHost:port:) fails to connect to Firestore emulator (SSL_ERROR_SSL: WRONG_VERSION_NUMBER)

[maierson]

Description

Expected Behavior:
Calling Firestore.firestore().useEmulator(withHost: "127.0.0.1", port: 8080) should reliably connect the app to the local emulator.

Actual Behavior:
• Emulator writes silently fail.
• Console logs include:

SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER

Only workaround: manually assign .settings.host, .isSSLEnabled = false, and .cacheSettings, which then works as expected.

Reproducing the issue

Steps to Reproduce:
1. Create a basic SwiftUI app
2. Call .useEmulator(...) before any Firestore usage
3. Attempt setData on any Firestore document
4. Observe no writes + error logs in Xcode console

Notes:
• Behavior persists even in clean project
• Works perfectly when switching to manual settings assignment
• This leads to misleading debugging time and inconsistent emulator usage across setups

// Fails (also with localhost)
Firestore.firestore().useEmulator(withHost: "127.0.0.0", port: 8080) 

// Works
let settings = Firestore.firestore().settings
settings.host = "127.0.0.1:8080"
settings.isSSLEnabled = false
settings.cacheSettings = MemoryCacheSettings()
Firestore.firestore().settings = settings

Note - combining useEmulator with manual settings also fails.

Firebase SDK Version

11.14.0

Xcode Version

16.4

Installation Method

Swift Package Manager

Firebase Product(s)

Firestore

Targeted Platforms

iOS

Relevant Log Output

Xcode:
11.14.0 - [FirebaseFirestore][I-FST000001] WriteStream (313033623233613938) Stream error: 'Unavailable: failed to connect to all addresses; last error: UNKNOWN: ipv4:127.0.0.1:8080: Ssl handshake failed (TSI_PROTOCOL_FAILURE): SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER: Invalid certificate verification context'
I0000 00:00:1750151041.618421 1574757 ssl_transport_security.cc:1697] Handshake failed with error SSL_ERROR_SSL: error:100000f7:SSL routines:OPENSSL_internal:WRONG_VERSION_NUMBER: Invalid certificate verification context

Emulator:
[2025-06-17T09:31:18.854Z] Jun 17, 2025 10:31:18 AM io.gapi.emulators.netty.HttpVersionRoutingHandler channelRead
INFO: Detected non-HTTP/2 connection.
 {"metadata":{"emulator":{"name":"firestore"},"message":"Jun 17, 2025 10:31:18 AM io.gapi.emulators.netty.HttpVersionRoutingHandler channelRead\nINFO: Detected non-HTTP/2 connection.\n"}}

If using Swift Package Manager, the project's Package.resolved

Expand Package.resolved snippet

{
  "originHash" : "e41f625ae3f23d23a9ec3274d71c573f85e66a943f95c95c77b070442e5b9eea",
  "pins" : [
    {
      "identity" : "abseil-cpp-binary",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/abseil-cpp-binary.git",
      "state" : {
        "revision" : "bbe8b69694d7873315fd3a4ad41efe043e1c07c5",
        "version" : "1.2024072200.0"
      }
    },
    {
      "identity" : "app-check",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/app-check.git",
      "state" : {
        "revision" : "61b85103a1aeed8218f17c794687781505fbbef5",
        "version" : "11.2.0"
      }
    },
    {
      "identity" : "appauth-ios",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/openid/AppAuth-iOS.git",
      "state" : {
        "revision" : "2781038865a80e2c425a1da12cc1327bcd56501f",
        "version" : "1.7.6"
      }
    },
    {
      "identity" : "confettiswiftui",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/simibac/ConfettiSwiftUI.git",
      "state" : {
        "revision" : "79666d42b882bf7921b1941fa7c636d681d77980",
        "version" : "2.0.3"
      }
    },
    {
      "identity" : "firebase-ios-sdk",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/firebase/firebase-ios-sdk",
      "state" : {
        "revision" : "45d327fcbe7793747295346c2209ad419bdead74",
        "version" : "11.14.0"
      }
    },
    {
      "identity" : "google-ads-on-device-conversion-ios-sdk",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/googleads/google-ads-on-device-conversion-ios-sdk",
      "state" : {
        "revision" : "70a7857886f065a40486a7607268781c49db04ae",
        "version" : "2.0.0"
      }
    },
    {
      "identity" : "googleappmeasurement",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/GoogleAppMeasurement.git",
      "state" : {
        "revision" : "406f72d0d5e9445fd1cf782db3e9e338cee2bed4",
        "version" : "11.14.0"
      }
    },
    {
      "identity" : "googledatatransport",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/GoogleDataTransport.git",
      "state" : {
        "revision" : "617af071af9aa1d6a091d59a202910ac482128f9",
        "version" : "10.1.0"
      }
    },
    {
      "identity" : "googlesignin-ios",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/GoogleSignIn-iOS",
      "state" : {
        "revision" : "65fb3f1aa6ffbfdc79c4e22178a55cd91561f5e9",
        "version" : "8.0.0"
      }
    },
    {
      "identity" : "googleutilities",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/GoogleUtilities.git",
      "state" : {
        "revision" : "60da361632d0de02786f709bdc0c4df340f7613e",
        "version" : "8.1.0"
      }
    },
    {
      "identity" : "grpc-binary",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/grpc-binary.git",
      "state" : {
        "revision" : "cc0001a0cf963aa40501d9c2b181e7fc9fd8ec71",
        "version" : "1.69.0"
      }
    },
    {
      "identity" : "gtm-session-fetcher",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/gtm-session-fetcher.git",
      "state" : {
        "revision" : "a2ab612cb980066ee56d90d60d8462992c07f24b",
        "version" : "3.5.0"
      }
    },
    {
      "identity" : "gtmappauth",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/GTMAppAuth.git",
      "state" : {
        "revision" : "5d7d66f647400952b1758b230e019b07c0b4b22a",
        "version" : "4.1.1"
      }
    },
    {
      "identity" : "interop-ios-for-google-sdks",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/interop-ios-for-google-sdks.git",
      "state" : {
        "revision" : "040d087ac2267d2ddd4cca36c757d1c6a05fdbfe",
        "version" : "101.0.0"
      }
    },
    {
      "identity" : "kingfisher",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/onevcat/Kingfisher.git",
      "state" : {
        "revision" : "7deda23bbdca612076c5c315003d8638a08ed0f1",
        "version" : "8.3.2"
      }
    },
    {
      "identity" : "leveldb",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/firebase/leveldb.git",
      "state" : {
        "revision" : "a0bc79961d7be727d258d33d5a6b2f1023270ba1",
        "version" : "1.22.5"
      }
    },
    {
      "identity" : "nanopb",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/firebase/nanopb.git",
      "state" : {
        "revision" : "b7e1104502eca3a213b46303391ca4d3bc8ddec1",
        "version" : "2.30910.0"
      }
    },
    {
      "identity" : "promises",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/google/promises.git",
      "state" : {
        "revision" : "540318ecedd63d883069ae7f1ed811a2df00b6ac",
        "version" : "2.4.0"
      }
    },
    {
      "identity" : "swift-protobuf",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/apple/swift-protobuf.git",
      "state" : {
        "revision" : "102a647b573f60f73afdce5613a51d71349fe507",
        "version" : "1.30.0"
      }
    },
    {
      "identity" : "swiftui-flow",
      "kind" : "remoteSourceControl",
      "location" : "https://github.com/tevelee/SwiftUI-Flow.git",
      "state" : {
        "revision" : "6dc1e0b452432976c27221d28de136fbb6cee56a",
        "version" : "3.1.0"
      }
    }
  ],
  "version" : 3
}

If using CocoaPods, the project's Podfile.lock

Expand Podfile.lock snippet

Replace this line with the contents of your Podfile.lock!

[google-oss-bot]

I couldn't figure out how to label this issue, so I've labeled it for a human to triage. Hang tight.

[rizafran]

Thanks for reporting, @maierson. I tried to reproduce and I was able to get the same error. It looks like you need to disable the SSL cert manually since I suspect that the SDK is trying to apply the SSL cert by default. With this, you may try adding both codes like in this sample code or just remove the code Firestore.firestore().useEmulator(withHost: "localhost", port: 8080) based on the docs.

[maierson]

Thanks @rizafran. What made it confusing is that (on my system) using both useEmulator AND settings (as in sample code) didn't work. Use emulator locks in ssl and applying settings after has no effect + makes setData() calls fail silently. On top of that Gemini advises that useEmulator disables ssl which is not the case though it would make a lot of sense. Hence filing this bug report: useEmulatorshould apply the correct settings by default (specifically disable ssl since the emulator doesn't accept them).