Bug Report: Stack Overflow in generated typed DSL bindings when a Firestore collection contains a self-referencing docRef field

[StudioReverbero]

Can we access your project?

• I give permission for members of the FlutterFlow team to access and test my project for the sole purpose of investigating this issue.

Current Behavior

Simply referencing ff.Collections.users in any DSL edit script crashes with a Stack Overflow — before any communication with the FlutterFlow server.

The typed DSL bindings generated by flutterflow ai init (in lib/flutterflow_project/schemas.dart) produce an infinite static-initialization cycle when a Firestore collection contains a docRef field that points back to the same collection. In my project, the users collection has blockedUsers and swipedBy fields containing references to other users documents (a common pattern in social/dating apps).

Root cause identified: in the generated schemas.dart, the UsersFields class contains fields like ffai.ProjectCollectionFieldHandle(..., type: ffai.docRef(Collections.users), ...). Collections.users is a static final whose initializer constructs UsersFields(), which itself references Collections.users before its initialization has completed — a Dart static-initialization re-entrancy cycle → infinite recursion → stack overflow.

Impact: any DSL action (Read/Query/Create/Update/Delete) referencing the affected collection crashes locally, as does any collection referencing it transitively — effectively blocking agent-driven Firestore edits (MCP/CLI) on the whole project.

Expected Behavior

Collections.users should initialize normally. Self-referencing docRef fields are a legitimate Firestore pattern and should be supported by the typed bindings generator — e.g., by making self-referencing field type handles lazy (resolved on first use) or by resolving docRef targets by collection name/id instead of by handle at static initialization time.

Steps to Reproduce

1. Create a FlutterFlow project with a Firestore collection users that includes at least one field of type Document Reference pointing to the users collection itself (e.g., blockedUsers: List<DocRef(users)>).
2. Run flutterflow ai init my-app --project <project-id> to scaffold the workspace and generate typed bindings.
3. Create a minimal DSL script containing only:
   print('before access');
   print(ff.Collections.users.name);
   print('after access');
4. Run it: dart run dsl/edit.dart --project-id <project-id> --dry-run
5. Observe: "before access" is printed, then the process crashes with a Stack Overflow. "after access" is never reached.

Environment: flutterflow_cli 0.0.37, flutterflow_ai SDK 0.0.36 (build 3dc1c5da), Dart 3.12.2 stable, Windows 11 x64.
Reproducible 100% of the time. Project ID: projet-unio-dh180w (access granted above).

Reproducible from Blank

• The steps to reproduce above start from a blank project.

Bug Report Code (Required)

IT4siMjfsI52rtxE0KqNacF7/TsUNU97RJ0escpCbw4bIYj2P4lzY876P0hvUvWlYXNIMWG2p14BwPOPvdjlJ8AVGw+BRphRys92TznKeFquMpOTF7qeX2tQMJpbJlyl1MKNuhQmOvJ2SmAewGemAeqQbB7ZJZ+xIUQ8Sq/LZO4=

Visual documentation

Minimal reproduction script (dsl/repro_stack_overflow.dart):

​```dart
import 'package:unii_app/flutterflow_project.dart' as ff;

void main() {
print('before access');
print(ff.Collections.users.name); // ← Stack Overflow here
print('after access');
}
​```

Output (run directly via dart run to bypass the CLI's generic error formatter):

​ before access Unhandled exception: Stack Overflow #0 new ListType (package:flutterflow_ai/src/dsl/types.dart:296:3) #1 listOf (package:flutterflow_ai/src/dsl/types.dart:309:41) #2 new UsersFields (package:unii_app/flutterflow_project/schemas.dart:641:16) #3 Collections.users (package:unii_app/flutterflow_project/schemas.dart:56:13) #4 Collections.users (package:unii_app/flutterflow_project/schemas.dart) #5 new UsersFields (package:unii_app/flutterflow_project/schemas.dart:690:47) #6 Collections.users (package:unii_app/flutterflow_project/schemas.dart:56:13) ... (frames #5/#6/#7 repeat identically ~10,700 times until the stack limit is hit) ​

The cycle: Collections.users (schemas.dart:56) constructs UsersFields(), whose swipedBy field (schemas.dart:690, listOf(docRef(Collections.users))) re-enters Collections.users's still-in-progress static initializer → infinite recursion.

Environment

- FlutterFlow version: current web version (July 2026) — bug is in the CLI/SDK, not the web editor
- flutterflow_cli version: 0.0.37
- flutterflow_ai SDK version: 0.0.36 (build 3dc1c5da)
- Dart SDK: 3.12.2 (stable)
- Platform: FlutterFlow AI CLI / MCP workspace (`flutterflow ai init`)
- Operating system and version affected: Windows 11 x64

Additional Information

This blocks the primary use case of the new FlutterFlow AI CLI/MCP: agent-driven edits (e.g., via Claude Code) involving any Firestore action on the affected project. Since my users collection is referenced transitively by nearly every other collection (comments, events, chats), effectively, all Firestore DSL operations crash locally.

I'm preparing a dating/community app for launch, and this prevented an automated fix of my account-deletion flow — I had to fall back to manual edits in the visual editor. Any social app with user-to-user references (blocked lists, followers, matches) will hit this same wall when adopting the MCP tooling.

A workaround suggestion: make self-referencing field type handles lazy in the generated code (e.g., late final or closure-based docRef targets), or resolve docRef targets by collection name/id rather than by handle at static-initialization time.