Troubleshooting
Start from what failed and move to the exact Typeship report, command, or configuration that resolves it.
Typeship keeps source analysis, Target Generation, repository Delivery, and release readiness separate. Start with the failed stage instead of regenerating everything repeatedly.
| Symptom | Inspect first | Next step |
|---|---|---|
| A Project cannot be created or refreshed | Definition source and resolver error | Debug the Definition or fix source access. |
| Diagnostics block a source pull request | Stable rule ID, evidence, and source coordinate | Fix the source, apply an exact remediation, or change policy deliberately. |
| One Target fails while others succeed | That Target's latest Generation | Read its error, warnings, provenance, and entitlement before retrying. |
| Generation succeeds but no pull request opens | Generation Delivery result and integration health | Restore GitHub access, add a repository Delivery, or accept Destination current. |
| A source check reports breaking changes | Objective compatibility details | Fix the contract or acknowledge the intentional break. Do not change a package version in the source pull request. |
Typeship – release readiness fails | Destination pull request and required version | Release the breaking change or regenerate an edited candidate. |
| A generated Target contains only 25 operations | Generation limits | The Free cap is working; the complete Definition and Diagnostics remain available. |
| An MCP client cannot connect or call tools | Transport, authorization challenge, and server doctor output | Use Connect MCP clients and the MCP error envelope. |
| The Typeship API returns an error | issues[].code, request_id, and next_steps | Follow API errors; do not branch on prose. |
Inspect one Project
typeship projects retrieve prj_...
typeship projects retrieve-integration-health prj_...
typeship projects retrieve-diagnostics prj_...
typeship projects list-generations prj_... --all
typeship targets list prj_...Project lists are intentionally lean. Retrieve the Project or list its Targets when you need Deliveries and Target state. Filter Generation history with --target-id when only one release stream is failing.
Retry only after changing something
Repeated Generation does not repair configuration or integration failures. Fix the boundary named by the error before running typeship projects generate <project_id> again.
Common examples include:
- an unreadable Definition;
- an unavailable generator edition;
- missing GitHub permission;
- overlapping destination directories;
- an incorrect package version; or
- an edited candidate branch.
When asking support for help, include the request ID, Project ID, Target ID, Generation ID, and public pull-request URL that apply. Do not send API keys, source headers, or private Definition contents.
next_steps. Retry once only after the boundary changed. Report IDs and status fields, but redact credentials and private Definition content.Debug an API contract that will not generate
From spec_error or a wall of warnings to a clean generation: read the message, find it in the reference, fix it in the spec or with a patch, regenerate.
Overview
Typeship's HTTP API for Definitions, Targets, Generations, Diagnostics, and agent-driven automation.