> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/developer-guide/guides/troubleshooting.md).
# Troubleshoot an Integration
Locate failed authentication, missing context, incomplete turns, unresolved writes, and missing delivery, then collect the evidence needed to recover.
Start with the last milestone you can prove: authenticated request, usable context, accepted turn, completed answer, confirmed external action, or recipient delivery. A later milestone cannot be inferred from an earlier one.
Start at the last verified milestone and investigate the next boundary before repeating work.
For Console sign-in, missing services, and session-start problems, use the [Console walkthrough troubleshooting](/developer-guide/guides/first-console-conversation.md#troubleshooting). For local installation and result-file issues, use the [starter troubleshooting](/developer-guide/guides/first-verified-conversation.md#troubleshooting).
## Find the Failing Boundary
| Symptom | Check first | Next action |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authentication fails | API family, regional host, workspace/organization, credential scope and expiry | Use [Choose Credentials](/developer-guide/getting-started/credentials.md) to select the Platform, Classic, or Scribe access flow |
| A service or entity is not found | Exact workspace and supplied identifiers; source acceptance versus projection/queryability | Inspect [Services](/developer-guide/platform-api/workspaces/services.md) and [Entity Resolve](/developer-guide/platform-api/data-world-model/entity-resolve.md); do not select an arbitrary production record |
| An SDK example does not compile | Package name, pinned version, lockfile, and Node version | Reproduce the [starter](/developer-guide/guides/first-verified-conversation.md) with `npm ci`; distinguish SDK drift from a runtime failure |
| A turn returns an acknowledgement but no final answer | `background_pending`, delivery protocol support, and returned receipt | Follow [web application delivery](/developer-guide/platform-api/conversations/serve-agent-from-web-app.md); an observer dashboard stream is not the per-chat delivery protocol |
| A connection drops after a turn was sent | Saved conversation ID and durable history | Read the conversation before resending; the original turn may have been processed |
| Approval is granted but the target did not change | Decision consumption, next supported turn, actual integration result, target read-back | Follow [approval-gated writes](/developer-guide/platform-api/integrations/approval-gated-integration-writes.md); reconcile an ambiguous target result before retrying |
| A tool cannot be tested | Tool family, endpoint identifiers, test permission, and applicable test operation | Follow [Tool Testing](/developer-guide/platform-api/functions/tool-testing.md); its generic execute operation does not execute every tool family |
| An SMS reply never arrives | Registration/routing, suppression, send acceptance, exposed delivery evidence | Follow [managed SMS testing](/developer-guide/guides/test-managed-sms.md); a created conversation is not a delivery receipt |
| A Scribe artifact is not ready | Correct deployment base, provider access, session mode, generation status, and review version | Follow [Scribe](/developer-guide/platform-api/scribe.md); generation acceptance is separate from a ready artifact |
| A test succeeds but production fails | Selected versions, actual channel, source freshness, tool access, and runtime differences | Compare the [deployment configuration](https://docs.concurrence.com/platform-overview/deployment-model) and rerun the failing case on its intended path |
## Preserve Evidence Before Retrying
Platform and managed-channel requests can return `503` during maintenance. A successful health check does not establish that those operations are accepting work. Check the response and the agreed status or support channel; do not treat a send acknowledgement, missing delivery receipt, or timeout as permission to send the same message again.
For an ambiguous request, keep the original identifiers and timestamp. Check durable state and the target system where applicable. A new conversation or retry can create new work; it is not a reconciliation mechanism.
Use the specific operation's retry guidance and exposed rate-limit information. There is no one platform-wide retry interval or rate limit. See [SDK Error Handling](/developer-guide/platform-api/platform-sdk/error-handling.md) and [Rate Limits](/developer-guide/operations/reference/rate-limits.md).
## Prepare an Escalation
Send the responsible implementation or support contact the API/channel, region, workspace, UTC timestamp, SDK version, selected service/configuration, conversation/run identifier, available request identifier, expected milestone, and last observed result. Include a minimal synthetic reproduction and the relevant error/status when possible.
Describe whether the outcome is known to have failed or remains unknown, and what retries or manual actions have already occurred. Use the agreed secure support route for sensitive evidence. Do not paste credentials, private transcripts, or patient records into public documentation issues.
## Verify Recovery
Repeat the smallest failing case, confirm the intended durable or external outcome, and confirm that retries did not create unintended duplicate work. Record the correction and add the failure case to the deployment's regression set. Close test conversations and reconcile pending actions using their owning lifecycle; closing a conversation does not undo a completed external write.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.concurrence.com/developer-guide/guides/troubleshooting.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
