OpenAgentsControl/.opencode/context/core/context-system/operations/error.md

Error Operation

Purpose: Add recurring errors to knowledge base with deduplication

Last Updated: 2026-01-06

---

When to Use

• Encountered same error multiple times
• Want to document solution for team
• Building error knowledge base
• Preventing repeated debugging

---

6-Stage Workflow

Stage 1: Search Existing

Action: Search for similar/related errors

Process:

1. Search error message across all errors/ files
2. Find similar errors (fuzzy matching)
3. Find related errors (same category)

Format:

Searching for: "Cannot read property 'map' of undefined"

Found 1 similar error:
  📄 development/errors/react-errors.md (Line 45)
     ## Error: Cannot read property 'X' of undefined
     Covers: General undefined property access
     Frequency: common

Found 2 related errors:
  📄 development/errors/react-errors.md
     ## Error: Cannot read property 'length' of undefined
     ## Error: Undefined is not an object

---

Stage 2: Check Duplication (APPROVAL REQUIRED)

Action: Present deduplication options

Format:

Options:
  [A] Add as new error to react-errors.md
      (Specific case: 'map' on undefined array)
  
  [B] Update existing 'Cannot read property X' error
      (Add 'map' as common example)
  
  [C] Skip (already covered sufficiently)

Which framework/category?
  [1] React (react-errors.md)
  [2] JavaScript (js-errors.md)
  [3] General (common-errors.md)
  [4] Create new: ___

Select option + category (e.g., 'B 1'):

Validation: MUST wait for user input

---

Stage 3: Preview (APPROVAL REQUIRED)

Action: Show full error entry before adding

Format:

Would update development/errors/react-errors.md:

Current (Line 45):
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## Error: Cannot read property 'X' of undefined

**Symptom**:

TypeError: Cannot read property 'X' of undefined

**Cause**: Attempting to access property on undefined/null object.

**Solution**:
1. Add null check
2. Use optional chaining (?.)
3. Provide default value

**Code**:

jsx // ❌ Before const value = obj.property

// ✅ After const value = obj?.property ?? 'default'

**Prevention**: Always validate data exists
**Frequency**: common
**Reference**: [Link]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Proposed update:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
## Error: Cannot read property 'X' of undefined

**Symptom**:

TypeError: Cannot read property 'X' of undefined TypeError: Cannot read property 'map' of undefined ← NEW TypeError: Cannot read property 'length' of undefined ← NEW

**Cause**: Attempting to access property on undefined/null object.
Common with array methods (map, filter) when data hasn't loaded.  ← NEW

**Solution**:
1. Add null check
2. Use optional chaining (?.)
3. Provide default value (especially for arrays)  ← UPDATED

**Code**:

jsx // ❌ Before const value = obj.property const items = data.map(item => item.name) ← NEW

// ✅ After const value = obj?.property ?? 'default' const items = (data || []).map(item => item.name) ← NEW

**Prevention**: Always validate data exists. For arrays, provide empty array default.  ← UPDATED
**Frequency**: common
**Reference**: [Link]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

File size: 98 lines → 105 lines (under 150 limit ✓)

Approve? (yes/no/edit):

Edit mode: Allow modification before adding

Validation: MUST get approval before proceeding

---

Stage 4: Add/Update

Action: Add or update error entry

Process:

1. Add/update error in target file
2. Follow error template format
3. Maintain file size <150 lines
4. Update "Last Updated" date

Template Format:

## Error: {Name}

**Symptom**: [Error message]
**Cause**: [Why - 1-2 sentences]
**Solution**: [Steps]
**Code**: [Before/After example]
**Prevention**: [How to avoid]
**Frequency**: common/occasional/rare
**Reference**: [Link]

---

Stage 5: Update Navigation

Action: Update README.md and add cross-references

Process:

1. Update README.md if new file created
2. Add cross-references to related errors
3. Link from related concepts/examples

---

Stage 6: Report

Action: Show results

Format:

✅ Added error to {category}/errors/{file}.md
🔗 Cross-referenced with X related errors
📊 Updated README.md (if needed)

Changes:
  - Updated existing error entry
  - Added 'map' and 'length' examples
  - File size: 105 lines (under 150 limit)

---

Deduplication Strategy

Similar Errors

Same root cause, different manifestations → Update existing to include new examples

Related Errors

Different causes, same category → Cross-reference between errors

Duplicate Errors

Exact same error already documented → Skip (already covered)

New Errors

Unique error not yet documented → Add as new error entry

---

Error Grouping

Group errors by framework/topic in single file:

• react-errors.md - All React errors
• nextjs-errors.md - All Next.js errors
• auth-errors.md - All authentication errors

Don't create: One file per error (too granular)

---

Examples

Add New Error

/context error for "hooks can only be called inside components"

Add Common Error

/context error for "Cannot read property 'map' of undefined"

Add Framework Error

/context error for "Hydration failed in Next.js"

---

Success Criteria

• Searched for similar errors?
• Deduplication options presented?
• Preview shown?
• User approved?
• Error follows template format?
• File size <150 lines?
• Cross-references added?
• README.md updated (if new file)?

---

Related

• standards/templates.md - Error template format
• guides/workflows.md - Interactive examples