---
name: troubleshoot
description: Structured error diagnosis for Dataverse operations. Prevents destructive fixes by requiring root cause analysis before any remediation. Use when an error occurs and the first instinct is to delete, remove, or recreate a component. Classifies errors, follows non-destructive diagnostic paths, and proposes fixes with explicit scope and blast-radius assessment.
argument-hint: "[error-message-or-context]"
---

# Troubleshoot Dataverse Errors

Structured error diagnosis that prevents destructive "fixes." When something breaks, diagnose before deleting.

## Arguments

- `$ARGUMENTS[0]` — The error message, error context, or description of what went wrong

## When to Use

- A tool call returns an error and your first instinct is to delete/remove/recreate something
- A solution import fails
- A flow won't activate
- A plugin registration fails
- A form renders incorrectly or shows errors
- A web resource throws console errors
- Any situation where the "quick fix" would be destructive

## CRITICAL RULE

**NEVER delete, remove, or recreate a component as a first response to an error.** Always diagnose first. The sitemap-deletion incident (deleting a sitemap to "fix" an import error) is the anti-pattern this skill prevents.

## Phase 1: Read the Error

Read the FULL error message. Not just the summary — the complete text including:
- Error code (e.g., `0x80045037`, `0x8004431a`, HTTP 400/403/500)
- Error message text
- Inner exception (if present)
- Stack trace (if present)
- The tool call that caused it and the parameters used

## Phase 2: Classify

| Error Pattern | Classification | Diagnostic Path |
|--------------|---------------|-----------------|
| "dependency", "missing component", "required component" | **Dependency** | Trace what's missing -> find or create it |
| "privilege", "permission", "access denied", 403 | **Permission** | Check security roles -> verify user/team assignments |
| "not found", "does not exist", 404 | **Missing Component** | Verify the component exists -> check spelling/casing of names |
| "already exists", "duplicate" | **Conflict** | Identify the existing component -> update instead of create |
| "invalid", "format", "schema", "type mismatch" | **Data/Schema** | Verify column types, required fields, data format |
| "connection", "timeout", "network" | **Infrastructure** | Check connection refs, environment availability, network |
| "0x80045037", "UIDataGenerationFailed" | **Platform Limitation** | Business rules cannot be created via API -> document and suggest UI |
| "activation", "state transition" | **State** | Check current state -> follow required state transitions |
| "import", "solution" | **Solution Import** | Check dependencies, component conflicts, managed/unmanaged conflicts |

## Phase 3: Non-Destructive Diagnosis

Follow the diagnostic path for the classified error:

### Dependency Errors
1. Identify exactly which component is missing from the error message
2. Search for it: `dataverse_list_tables`, `dataverse_list_columns`, `dataverse_list_web_resources`, etc.
3. If it exists but in a different solution: add it to the required solution
4. If it doesn't exist: create it (this is additive, not destructive)

### Permission Errors
1. Identify which user/team is affected
2. Check their security roles: `dataverse_get_user` -> `dataverse_list_security_roles`
3. Identify which privilege is missing
4. Add the missing privilege (additive fix)

### Missing Component Errors
1. Verify the exact name/ID — schema names are case-sensitive
2. Check if it was recently deleted (user may have removed it unknowingly)
3. Check if it exists but with a different name or in a different solution
4. If truly missing: create it

### Solution Import Errors
1. **DO NOT delete components to resolve import errors**
2. Read the full error — it usually names the specific missing dependency
3. Check if the dependency exists in the target environment
4. If missing: create the dependency first, then retry import
5. If it's a managed/unmanaged conflict: this is a versioning issue — consult with user on resolution strategy

### State Transition Errors
1. Check the component's current state (active/draft/disabled)
2. Follow required transitions: e.g., Active -> Draft (deactivate) -> delete
3. For flows: deactivate before deleting; check connection refs before activating

## Phase 4: Propose Fix

Present the fix with explicit scope:

```
**Diagnosis:** [What's wrong and why]

**Proposed Fix:** [What will be changed]
- Will modify: [specific components]
- Will NOT touch: [related components that are safe]
- Reversible: [yes/no — and how to reverse if yes]

**Proceed?**
```

## Phase 5: Destructive Gate

If and ONLY if the diagnosis concludes that the only viable fix IS destructive (must delete/recreate):

1. Explain WHY a non-destructive path doesn't work
2. List what will be deleted and what depends on it
3. Assess blast radius: "Deleting X will also affect Y and Z because..."
4. Get EXPLICIT user confirmation for EACH destructive action
5. Recommend backing up the component first if possible (export solution, save formxml, etc.)

## Common Error Quick Reference

| Error | Root Cause | Fix |
|-------|-----------|-----|
| Flow won't activate | Missing connection references | Create and wire connection refs -> retry activation |
| `0x80045037` on business rule create | Platform limitation | Cannot create via API — create in Dataverse UI |
| Solution import "missing dependency" | Component referenced but not in target | Create the dependency first, then retry import |
| Plugin registration "type not found" | Missing `plugin_types` parameter | Add explicit `plugin_types` list to registration call |
| Form "field not found" error | Column doesn't exist or wrong logical name | Verify column: `dataverse_list_columns(table)` |
| BPF activation fails silently | Missing publisher prefix in uniquename | Recreate BPF with `{prefix}_{bpfname}` format |
| Web resource "null reference" in console | Field referenced in JS not on the form | Check form fields: `dataverse_get_form` -> verify field exists on form |

## Guardrails

- **Diagnose before acting.** Complete Phases 1-3 before proposing any fix.
- **Non-destructive paths first.** Always look for additive solutions (create missing component, add permission, update configuration) before considering destructive ones.
- **One fix at a time.** Don't chain multiple fixes together. Apply one fix, verify it worked, then proceed to the next issue.
- **If you don't understand the error:** say so. Ask the user for more context rather than guessing at a fix.

## Validation

After applying a fix:
- Retry the original operation that failed
- Verify the error is resolved
- Check that the fix didn't introduce new issues (e.g., if you added a missing component, verify it's correctly configured)
- Report: original error, diagnosis, fix applied, verification result