Troubleshooting
Start from what failed and move to the exact Typeship report, command, or configuration that resolves it.
Start with the stage that failed: fetching the Spec, generating a Target, delivering files, or publishing a release. Inspect that stage’s result before retrying.
| Symptom | Inspect first | Next step |
|---|---|---|
| A Project cannot be created or refreshed | Spec source and resolver error | Debug the Spec or fix source access. |
| Diagnostics block a source pull request | Stable rule ID, evidence, and source location | Fix the source, review and apply a suggested patch yourself, or change the Diagnostic policy. |
| One Target fails while others succeed | That Target's latest Generation | Read its error, warnings, and operation limits before retrying. |
| Generation succeeds but no pull request opens | Generation Delivery result and integration health | Restore GitHub access, or add a repository Delivery. If the package already matches the repository, there is nothing to deliver. |
| 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 fails | Destination pull request and required version | Release the breaking change or regenerate an edited Draft. |
| A Target integration conflicts | Draft status: action_required, reason: conflict, and each file's conflict.kind | Resolve each conflict by keeping a side or supplying final content, then let Typeship continue the Draft. |
| A required package check fails | The named check's reason and URL on the latest Draft commit | Fix code or check configuration on the Draft and push a descendant commit. Typeship reruns integration and every required check. |
| A required check is unavailable or not assessed | The Target’s stored checks and the Draft’s checks, head_sha, and check URLs | Follow Configure package checks and make the configured check report on the latest Draft commit. Typeship reuses an earlier result only when the package contents and check configuration are unchanged. |
| Latest-release comparison is unknown | compatibility_release | Inspect the unavailable evidence. After review, a repository writer may apply typeship:breaking-approved to this Draft. An insufficient version bump must still be fixed. |
| Publishing fails after merge | The Release and failing destination status | Fix repository or registry configuration, then retry that release. Do not regenerate or reuse the version with different bytes. |
| A generated Target contains only 25 operations | Generation coverage | The Free cap is working; the complete Spec 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. |
| A Typeship API call fails or succeeds with a later delivery problem | The JSON body's top-level request_id; for raw responses, the Request-Id header; for errors, errors[].code | Follow API errors and request IDs; do not branch on prose. |
Inspect one Project
typeship projects get prj_...
typeship spec-revisions get srev_... --include diagnostics
typeship generations list --project-id prj_... --all
typeship targets list --project-id prj_...Project lists return summaries only. List a Project's Targets to see Deliveries and Target state. Filter Generation history with --target-id when only one release stream is failing.
For a repository problem, retrieve its Delivery and inspect status, typed issues, required_checks, and last_event.
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 Spec;
- missing GitHub permission;
- overlapping destination directories;
- an incorrect package version; or
- an edited Draft branch.
When asking support for help, include the relevant JSON response's top-level request_id. For a raw, text, file, bodyless, HEAD, or redirect response, capture the Request-Id response header instead. Include the Project ID, Target ID, Generation ID, and public pull-request URL that apply. Do not send API keys, source headers, or private Spec contents.
next_steps. Retry once only after the boundary changed. Report IDs and status fields, but redact credentials and private Spec content.Recover a stale Draft read
A 409 resource_changed on a Draft read means the Draft changed after you read it, or it has a commit Typeship has not integrated yet. Follow the Draft status: retrieve the Draft while its status is working, then act on its current head_sha. Non-overlapping work is preserved. If a conflict reappears after its file contents or kind of conflict changes, review it again; an earlier resolution does not approve the new change.
An adopted package has no earlier Typeship Generation to compare against, so its first Draft reports no_common_version conflicts. Treat the repository as the current code, then keep yours or choose generated for each conflict. Later updates compare against the result you accept.
If Typeship reports that it cannot read the generated files from the last merged package, and the conflict kind is not no_common_version, do not approve the Draft using an earlier result. Check the repository connection and regenerate once. If the error remains, contact support with the Project, Target, Generation, and request IDs.
If a maintainer merges a red Draft because release readiness is not protected, Typeship does not create a Release or start publishing. It retires that Draft and starts a fresh review from the default-branch change. Add Typeship Release to branch protection so this recovery remains exceptional.