Limitations
Honest boundaries: what Google Forms can block, what gform will not fake, and how to recover.
Related: file uploads · artifacts · roadmap · concepts
Reliability model
| Layer | Expectation |
|---|---|
| GForm (deterministic) | Schema, merge order, pools/variants, artifact layout, reason codes |
| Google UI (external) | DOM, Drive picker, throttling, and page flows can change |
| Headed + TTY assist | Soft walls pause; you finish the step, press Enter |
| Headless | Soft walls fail with a tip — never counted as success |
| Hard walls | Stop with reason; keep manifests / history / screenshots when possible |
A failed interaction should leave an inspectable artifact (gform run view <id>) whenever the run got far enough to allocate one.
Soft walls (human assist)
Assist needs a headed browser and a TTY. Headless never pauses for Enter. Disable with --no-assist / -na.
| Wall | Assist |
|---|---|
| CAPTCHA / unusual traffic | Solve in browser — no bypass |
| Login / permission | Sign in in browser, or gform auth create + --auth |
| Field validation after submit | Fix answers in browser |
| File uploads | Prefer action: file + source (local / gdrive / remote). When Google only exposes a Drive picker, auto-attach can fail → headed assist. Map: file-uploads |
| Auto-fill miss (odd widget / DOM drift) | Headed + assist: fix in browser, Enter |
pause / assist-only file under headless | Fail assist-headed-required |
| Manual submit while paused | Fail assist-advanced — do only the asked assist, then Enter |
Failed assists are not success — --once / -sd / unique stay clean.
Hard walls (stop + reason + keep state)
| Wall | Why |
|---|---|
| Form closed / not accepting | Owner closed it |
| Already responded | Limit-to-1 for this Google account |
| Timeout / browser closed mid-run | No recoverable page state |
--strict + invisible captcha flag | Early abort by request |
--strict + collect-email without --auth | Email collection needs a signed-in profile |
Expected external limitations
- Login walls and organization / SSO restrictions
- One-response limits and already-responded states
- Visible and invisible captchas
- Owner validation / question changes after you wrote YAML
- Google DOM and Forms UI changes
- File-picker / Drive UI behavior (especially under concurrency)
- Browser and WSL constraints (Windows
.exeoften not CDP-controllable from WSL) - Network failures and Google throttling
- High-concurrency authenticated file uploads — flaky; prefer lower concurrency and owned test forms
Known implementation limitations
- gform does not drive the full Google Drive picker UI as a first-class robot; it attaches when a settable file input / chooser path works, else assist
- Concurrent workers can race on picker / input attachment — tracked as reliability work (roadmap)
- Live batch terminal can repeat similar notices per worker — aggregation is planned, not shipped
- Offline
verifydoes not download Drive / remote bytes profiles/at repo root is not loaded at runtime (auth profiles live under$GFORM_HOME/auth/)
Out of scope (by design)
| Thing | Why |
|---|---|
| CAPTCHA / bot-challenge bypass | Abuse vector; assist only |
| Headless email+password Google login in YAML | Unsafe and brittle — use gform auth create |
| Unauthorized bulk submission / survey manipulation | Not the product |
| Guaranteed survival after the owner redesigns the form | Update YAML; use verify --check |
Recommended mitigations
| Situation | Mitigation |
|---|---|
| Learning a form | --policy demo or --headed -ko on a TTY |
| Interactive rematch (mime/size/fetch, login, headed GUI fail) | -H -pa on a TTY (refused with -j / -s / CI; headless ignores -pa with warn) |
| Unattended public form | Complete YAML + headless + --no-assist if soft walls must not pause |
| Login / collect-email | Auth profile + --auth |
| File uploads | Explicit source; --auth for gdrive; start with concurrency 1 |
| Drift | gform inspect + verify --check |
| Failure | gform run last / run view <id> / --pw-trace / -d |
| Host confusion | gform doctor --browser · gform br setup |
What works well today
- Public forms (no login)
- Signed-in forms after
auth create+--auth(including collect-email) - Soft walls with
--policy demo|watch+ assist on TTY - Multi-page radio / checkbox / text / dropdown / linear / rating + Next/Submit
- Grid rows scaffolded as
Parent — Rowradios - Batches with pools +
rotate/random/zip - Artifact-backed diagnosis and
gform restore
Planned work
Do not treat the roadmap as shipped. Phases cover a pressure harness, file-picker hardening, concurrency green tests, batch log aggregation, and regression gates — under owned test forms only.