Spurious “GET DOCUMENT returned null” immediately after update() in FirestoreCollection listener

[Shay-M]

Environment:

• Godot Engine: 4.4.1.stable.official
• Plugin: Firestore v2.3 (downloaded from Godot Asset Library)
• Platforms: Windows, Android

---

Description

Client A and Client B both attach real‑time listeners to the same Firestore document. When Client B immediately patches the doc, a spurious GET error appears:

ERROR: [Firebase Error] >> Action in error was: 0 (GET DOCUMENT)
get_document returned null for testdoc

even though the listener then recovers and fires correctly.

Minimal Test Controller Code

# File: res://Scenes/TestControllerDirect.gd
extends VBoxContainer

@onready var auth       = Firebase.Auth
@onready var games_coll = Firebase.Firestore.collection("games")

@onready var btn_login_a   : Button   = $HBoxContainer/BtnLoginA
@onready var btn_login_b   : Button   = $HBoxContainer/BtnLoginB
@onready var btn_create    : Button   = $BtnCreateDoc
@onready var btn_listen    : Button   = $BtnListen
@onready var btn_patch     : Button   = $BtnPatchMove
@onready var txt_log       : TextEdit = $Log

var listener_conn = null
var current_user_id   = ""
var current_user_name = "?"

func _ready() -> void:
    btn_login_a.pressed.connect(Callable(self, "_on_btn_login_pressed").bind("a@a.com","123456"))
    btn_login_b.pressed.connect(Callable(self, "_on_btn_login_pressed").bind("b@b.com","123456"))
    btn_create.pressed.connect(_on_btn_create_doc_pressed)
    btn_listen.pressed.connect(_on_btn_start_listening_pressed)
    btn_patch.pressed.connect(_on_btn_patch_move_pressed)

    auth.login_succeeded.connect(_on_login_succeeded)
    auth.login_failed.connect(_on_login_failed)

    _log("🔰 Ready. Click Login A or B.")

func _on_btn_login_pressed(email, pwd) -> void:
    _log("→ auth.login_with_email_and_password(%s)" % email)
    auth.login_with_email_and_password(email, pwd)

func _on_btn_create_doc_pressed() -> void:
    if current_user_id == "":
        _log("⚠️ Cannot create: not logged in")
        return
    _log("→ games_coll.add(\"testdoc\", {...})")
    var payload = {
        "player1_uid": current_user_id,
        "status":      "waiting",
        "last_move":   []
    }
    await games_coll.add("testdoc", payload)
    _log("✅ add/overwrite completed")

func _on_btn_start_listening_pressed() -> void:
    _log("→ games_coll.get_doc(\"testdoc\") and on_snapshot…")
    var doc_ref = await games_coll.get_doc("testdoc")
    if not is_instance_valid(doc_ref):
        _log("⚠️ get_doc returned null for testdoc")
        return
    if listener_conn:
        listener_conn.stop()
    listener_conn = doc_ref.on_snapshot(_on_snapshot, 3)
    _log("✅ listening for real‑time updates on testdoc")

func _on_btn_patch_move_pressed() -> void:
    _log("→ patch testdoc.last_move → [3,4]")
    var doc_ref = await games_coll.get_doc("testdoc")
    doc_ref.add_or_update_field("last_move", [3,4])
    await games_coll.update(doc_ref)
    _log("✅ update completed")

func _on_snapshot(changes: Dictionary) -> void:
    _log("--- snapshot fired ---")
    for child in games_coll.get_children():
        if child.doc_name == "testdoc":
            _log("doc data = %s" % child.get_unsafe_document())
            return
    _log("⚠️ Document node not found")

func _on_login_succeeded(res: Dictionary) -> void:
    current_user_id   = res.get("localid","")
    current_user_name = res.get("email","?").split("@")[0]
    _log("✅ login_succeeded: uid=%s email=%s" % [current_user_id, res.get("email","?")])

func _on_login_failed(code,msg) -> void:
    _log("❌ login_failed: code=%d msg=%s" % [code,msg])

func _log(msg: String) -> void:
    txt_log.text += msg + "\n"
    txt_log.scroll_vertical = txt_log.get_line_count()
    print(msg)

Observed Console Log

[50:30][?] 🔰 Ready. Click Login A or B.
[50:32][?] → auth.login_with_email_and_password(a@a.com)
a: Authenticated as a@a.com
[50:33][a] ✅ login_succeeded: uid=tEJpx9DusiStnc1Ys3HflciCF5Z2 email=a@a.com
[50:35][a] → games_coll.add("testdoc", {...})
[50:35][a] ✅ add/overwrite completed
[50:38][a] → games_coll.get_doc("testdoc") and on_snapshot…
[50:41][a] ✅ listening for real‑time updates on testdoc
[50:48][?] → auth.login_with_email_and_password(b@b.com)
b: Authenticated as b@b.com
[50:49][b] ✅ login_succeeded: uid=vGTik1sOXvTCFKEKTiPERksdtlC3 email=b@b.com
[50:52][b] → games_coll.get_doc("testdoc") and on_snapshot…
[50:54][b] ✅ listening for real‑time updates on testdoc
  ERROR: [Firebase Error] >> Action in error was: 0 (GET DOCUMENT)
get_document returned null for  testdoc

Expected vs. Actual

• Expected: The two players could listen to changes. - use on_snapshot
• Actual: In fact, only one side manages to listen to their changes..

Thanks in advance for any insight! I’d love to know if there’s a configuration flag or code pattern I’m missing.

—
Feel free to link to this issue or ping me if you need more logs or a minimal reproduction project.

[WolfgangSenff]

That is a really weird use case, not one I took into account when designing it. It might be better to try to find a way to do that through the realtime database instead. I'm not able to look at the code at the moment, but I do have some further thoughts, once I'm back at my desk. I'll have to read your post more carefully as well.

[Shay-M]

The GET error only appears on Client B, not on the original document creator.
Let me know if you need any more details.

[WolfgangSenff]

@Shay-M - wait, you said only one side listens for changes successfully? They both print off that they are listening for changes. Am I misunderstanding it?

[WolfgangSenff]

Here's the culprit, if one of them doesn't listen for very long or at all, seemingly: https://github.com/GodotNuts/GodotFirebase/blob/main/addons/godot-firebase/firestore/firestore_listener.gd#L33

[WolfgangSenff]

Ahh, I see what's happening I think.
https://github.com/GodotNuts/GodotFirebase/blob/main/addons/godot-firebase/firestore/firestore_collection.gd#L45

Can you go to that line and set a breakpoint and test it again? It should hit on the one that's throwing the null error (make sure that's the one that it has hit from), and then what's happening is that it's replacing the child. Then, anything listening has their document replaced underneath them. I suspect what I have to do instead is replace the unsafe document with the new one, leaving the exact actual node in the tree, because otherwise it invalidates all the references when the node itself is replaced. So like:

@onready var A_Node = %ANode

func _ready() -> void:
  %ANode.replace(Node.new(), true) # Invalidates A_Node completely, probably crapping up the underlying listener

I'll have to look into, first off, creating a test case for this somehow in my test harness, and for two, changing it so the update, if it finds it in the cache, just updates the underlying dictionary instead of swapping out the node itself. Not sure why I thought that would work. Funnily enough, I do see that, in the code link at the top that I posted, it isn't actually using the is_listener value in the function. I'm not sure how that snuck by. I'm sure that was intended to differentiate between when to add the node and when to find it already there and update the underlying document instead of replacing it. Silly me. I should have a fix today.

[WolfgangSenff]

Alright, @Shay-M, I've come up with a totally different implementation for Firestore document listeners that would be a) much faster, and b) much cheaper. There's only one extra requirement: you have to allow the use of the Realtime Database as well. Would you be willing to allow that, if the implementation of Firestore document listeners required it? It's a pretty big change to the library, but at the same time it would be totally invisible to you, as it only involves the underlying structures, nothing in the API interface.

Incidentally, for the add_or_update_field call you have, you can actually just use the dictionary indexing syntax, if you're interested. In other words:

doc_ref.add_or_update_field("last_move", [3,4])

becomes:

doc_ref["last_move"] = [3,4]

or even:

doc_ref.last_move = [3, 4]

[Shay-M]

Yes, I’m totally fine with adding the Realtime Database as part of the background implementation if that makes the Firestore listeners faster and more stable. Thank you very much for working on this improvement! Also, thank you for explaining the cleaner syntax for updating fields.

[WolfgangSenff]

No problem! I am glad to hear it, re: rtdb. I've already started on an implementation for it, but it will take a little while due to the complexity of it - basically requires writing changes found in the document out to the rtdb in a "canonical" place, and getting the updates, and rehydrating the associated document with those values. Only changes will be written to the rtdb, so hopefully that will minimize the total space used, which is basically all that is charged for in the rtdb, I believe. It might be other stuff too, like ingress and egress, but regardless, it's massively cheaper still than Firestore. Like 100s of thousands of dollars cheaper for millisecond-level, or even faster, update speeds.

[WolfgangSenff]

@Shay-M - alright, are you in the Discord server? I believe I have completed the changes, but I want you and I'm trying to find others to test it in different ways, to try to break it. My test harness app isn't super-well designed in order to try to test this specific usecase, in part because the library prevents more than one listener per document per app run. I could try to update that, but it would be quite a hassle, so I need people with valid test-cases like yourself to be able to try it out. Let me know if you're available to test the code, and feel free to join the Discord if you're not in it, so I can coordinate with the testers better.

[Shay-M]

I’ve joined the Discord server.
my username is banana_for_all, I'd be happy to discuss the details there.