# Troubleshoot an SDK release

Open the affected target's release view. Keep the intended version, generation PR,
release PR and linked workflow run together while investigating. Never paste
tokens, private logs or unredacted provider responses into an issue.

| Symptom | Next step |
|---|---|
| Repository absent | Refresh authorization with **I don't see my repo**; check the installation's selected repositories. |
| Approval pending | Have an installation administrator review the App update on GitHub. |
| Secret missing or name collision | Inspect the named repository/environment secret. Preserve a credential used by another workflow; do not overwrite it blindly. |
| OIDC authentication failed | Compare exact owner, repository, workflow and environment with the provider's trusted publisher. |
| Workflow failed | Read the failing job. Fix the cause before using the release view's targeted retry. |
| Released, no receipt yet | Check the linked run and callback step. Let reconciliation inspect provider truth; do not fabricate or replay callback bodies. |
| Registry says published, Studio disagrees | Check the exact package/version and attribution. Existence alone does not prove it came from this release. |
| Repository-managed publishing detected | Compare workflows and publishing preference with your intended configuration. A repository administrator may have changed them. |
| Unlink cleanup incomplete | Follow the manual inventory, including provider credentials; losing App access is not proof of cleanup. |

## One target succeeded and another failed

Do not rerun the whole release set or republish the successful child. Use the
per-target state to identify the unfinished version, fix its failure, and retry
only that child. Keep the intended version unchanged unless the registry already
contains incompatible bytes under it. Ask support when the retry cannot be tied
to an exact occurrence.

## The wrong version or content was published

Treat released versions as immutable. Preserve the incident evidence, stop further
Doctorine automation if needed, and prepare a corrected version through a new
reviewed release. Use the registry's supported deprecation or yank controls only
after checking consumer impact. Do not delete and recreate a version or move a
tag to make the history look successful.

## Custom code conflicts

Resolve the change on the base branch, rebuild and review the resulting generation
PR. See [Custom code](/guides/custom-code/). A closed generation PR can be reopened on
GitHub; creating unrelated release branches does not repair its lifecycle.

## Ask for help

Share the target, bounded error/status shown in Studio, intended version and links
to the relevant private release/run with authorized support. Exclude credentials,
customer payloads and raw request/response bodies. An estimated or unknown state
must be reconciled, not relabeled as published.

## Related pages

- [Doctorine SDK documentation](../index.md)
- [Publish SDKs to registries](./publish-sdks.md)
- [Set up a registry publisher](./registry-setup.md)
- [Doctorine App permissions](./app-permissions.md)
- [Keep custom code during regeneration](./custom-code.md)
- [Plans, disable and offboarding](./plans-and-offboarding.md)

# Agent Instructions

This portal answers questions programmatically. To receive a synthesized,
source-cited answer instead of crawling page by page, append the `?ask=`
query parameter to any page URL on this site:

    /guides/quickstart?ask=how+do+I+authenticate

Optional parameters:

- `&goal=<what-you-are-trying-to-do>` steers the answer toward your
  objective (e.g. `&goal=write+a+python+client`).
- `&version=<label>` scopes the answer to a mounted version when the
  portal publishes more than one.

The response is `text/markdown`: the answer followed by a `# Sources` list
of the portal pages it was grounded in. Status codes are the contract:

- `200` — the answer; `402` — the portal owner’s plan or answer credits are
  exhausted (surface this to your operator; do NOT retry); `429` — you are
  rate-limited; back off for the `Retry-After` seconds; `503` — the answer
  lane is temporarily unavailable; fall back to crawling the `.md` pages.

For the full corpus map read `llms.txt` at the site root; for the tool
surface (search + page fetch as MCP tools) see `/mcp`.