---
title: "Troubleshooting"
description: "Start from what failed and move to the exact Typeship report, command, or configuration that resolves it."
url: https://typeship.dev/docs/guides/troubleshooting
markdown: https://typeship.dev/docs/guides/troubleshooting.md
section: "Get started"
---
> ## Documentation index
> Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt.
> Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page.

# 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](https://typeship.dev/docs/guides/debug-a-spec) 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](https://typeship.dev/docs/guides/release-a-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](https://typeship.dev/docs/guides/mcp-clients) and the MCP error envelope.                                    |
| The Typeship API returns an error              | `issues[].code`, `request_id`, and `next_steps`                | Follow [API errors](https://typeship.dev/docs/typeship-api/errors); do not branch on prose.                                            |

## Inspect one Project

```bash
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.

> **For AI agents:** Run the inspection commands, identify the earliest failed boundary, and follow its 
> 
> `next_steps`
> 
> . Retry once only after the boundary changed. Report IDs and status fields, but redact credentials and private Definition content.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)