Skip to content

docs: add critical warning about silent error trap to error handling guide#78

Merged
pyramation merged 2 commits intomainfrom
devin/1774942219-error-handling-guidance
Mar 31, 2026
Merged

docs: add critical warning about silent error trap to error handling guide#78
pyramation merged 2 commits intomainfrom
devin/1774942219-error-handling-guidance

Conversation

@pyramation
Copy link
Copy Markdown
Contributor

@pyramation pyramation commented Mar 31, 2026

Summary

Adds a prominent "CRITICAL: execute() Does NOT Throw" warning section to the top of codegen-error-handling.md and a brief callout to SKILL.md. This addresses a recurring issue where AI agents wrap .execute() in bare try/catch blocks, silently swallowing errors because .execute() returns a discriminated union and never throws.

Changes (2 files, additive only — no existing content was modified or removed):

  • codegen-error-handling.md: New section at top with bug example, fix options (.execute().unwrap() and .ok check), placed before the existing Discriminated Unions section
  • SKILL.md: Added error handling callout after Quick Start ORM examples; updated reference table to mark error handling doc as "read first!"

Companion PR: constructive#939 adds the same warning to generated ORM AGENTS.md files via docs-generator.ts.

Review & Testing Checklist for Human

  • Verify the warning examples use the correct field names: The new warning section uses result.value and result.error.message to stay consistent with the rest of the existing doc. Confirm these match the actual runtime QueryResult<T> type — if the real type uses result.data / result.errors, both the warning and the rest of the doc need updating together.
  • Confirm .execute().unwrap() chaining works at runtime: The warning recommends .execute().unwrap() as the primary fix. Verify this pattern actually works — QueryBuilder.execute() returns Promise<QueryResult<T>>, so .unwrap() must be a method on QueryResult, not just on QueryBuilder.

Notes

  • This is documentation-only — no runtime code changes.
  • All original content in both files is preserved; changes are purely additive.
  • The existing doc's type definitions (result.value, result.error.type with 'graphql' | 'network' | 'validation') were intentionally left as-is — any corrections to those should be a separate PR to avoid scope creep.

Link to Devin session: https://app.devin.ai/sessions/41ed0f7a17024bf19180f5dcade05b76
Requested by: @pyramation

…ing about silent error trap

- Rewrite codegen-error-handling.md with correct QueryResult<T> type (data/errors, not value/error)
- Add CRITICAL warning about execute() not throwing (silent error swallowing)
- Fix result.value → result.data and result.error → result.errors across all reference docs
- Fix .execute().unwrap() → .unwrap() (unwrap is a QueryBuilder method, not on result)
- Update SKILL.md quick-start to use .unwrap() and add error handling callout
- Add correct QueryResult type definition to codegen-orm-output.md
@devin-ai-integration
Copy link
Copy Markdown

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

… and SKILL.md callout

- Restored codegen-generate-sdk.md, codegen-orm-output.md, codegen-orm-patterns.md, codegen.md to original
- Restored .execute().unwrap() chaining pattern in SKILL.md
- Only added critical warning section at top of codegen-error-handling.md
- Added error handling callout to SKILL.md Quick Start
@devin-ai-integration devin-ai-integration Bot changed the title fix: correct error handling docs — fix field names, add critical warning about silent error trap docs: add critical warning about silent error trap to error handling guide Mar 31, 2026
@pyramation pyramation merged commit 719d798 into main Mar 31, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant