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:

// ❌ 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**:
```markdown
## 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