Find the boundary that failed
Diagnose package, schema, execution and transport failures without changing several layers at once.
Source and verification context ⌄
Source-guided
Inspect the source ↗Repository links may require access. Source inspection is separate from a clean public-package installation.
Get the shape of this guide.
Move through the ideas, inspect their relationships, or make a focused reading path. The complete guide stays below.
Capture a small reproducible case
Record the package versions or commit, operation key and version, chosen adapter and sanitized request. Keep the first relevant error and trace identifier. Start from the boundary where the failure appears instead of reinstalling or regenerating the entire project.
Read the supporting context
Remove provider credentials and personal data from a reproduction. A fixture subject and a disposable handler are usually enough to isolate schema, registry or approval behavior.
Explore a section, then continue with the complete article below.
Capture a small reproducible case
Record the package versions or commit, operation key and version, chosen adapter and sanitized request. Keep the first relevant error and trace identifier. Start from the boundary where the failure appears instead of reinstalling or regenerating the entire project.
Remove provider credentials and personal data from a reproduction. A fixture subject and a disposable handler are usually enough to isolate schema, registry or approval behavior.
Read the signal at the stage it describes.Trace the mechanism · 3 ways to look closer＋
A trace can help explain a request, but timing and durability determine what it establishes.
The boundary stopped the operation before the effect.
The result reports a meaningful failure before handler entry.
Carry operation key, version and trace context.
The operation identity and failure category show where to investigate.
A precondition denial is different from a business failure after execution began.
Fix the applicable input or trusted context, or follow the authorized approval path. Preserve that distinction in the explanation.
Where this explanation comes from
An authored situation, grounded in the linked source guides. Choosing a case explores its expected responsibilities; it does not execute an operation.
Use the symptom to choose the next check
A request can fail before the handler, inside business logic or after the handler returns. Distinguishing those points prevents changes that make the interface appear fixed while hiding the real issue.
| Symptom | Check first | Avoid assuming |
|---|---|---|
| Package cannot be resolved | Selected registry, exact package version and public exports | A workspace path is a published import |
| Spec or handler missing | Registration, key/version and binding | A declaration executes merely because it exists |
| VALIDATION_FAILED | Declared input and adapter input mapping | A policy rejection caused the failure |
| UNAUTHENTICATED | Trusted adapter context | A role field in input authenticates the caller |
| APPROVAL_REQUIRED | Requirement, receipt and approval port | Any token-shaped value authorizes a request |
| Invalid output | Handler return value and output model | The failed response rolled back earlier effects |
| API works, MCP fails | Tool schema, identity and result handling | Both transports have identical wire semantics |
Isolate one layer at a time
First confirm the operation is registered and bound. Then test the registry with the same valid input and a deliberately constructed fixture context. Finally invoke the actual adapter. This tells you whether the problem is in the handler or in transport/context mapping.
For approval failures, inspect the reason. Missing evidence and a missing approval runtime require different fixes. Keep the fail-closed behavior while correcting the host configuration.
Check documentation provenance
If a copied snippet refers to a different metadata shape, import path or command flag, compare it with the selected version's source. The source-guided pages here deliberately identify their snapshot so differences can be examined.
When reporting a docs defect, include the page URL, package version, smallest failing snippet and expected result. That is more actionable than a screenshot of a large terminal log.