Diagnose missing Python traces, steps, project assignment, and context.
Common checks
Symptom
Check
No trace appears
Confirm the entrypoint enters sovara_client.trace(...). Check the terminal for a Sovara warning.
A trace appears without model or tool steps
Call sovara.auto_instrument() once at startup, before creating provider clients.
CompatibilityError
The Sovara server is older than the SDK. Update the Sovara server.
An evaluation sample is missing from Traces
Look in Evaluations; the main Traces view excludes evaluation-owned samples.
Lessons are missing
Check that the key allows lessons, the proposal was applied, automatic injection is enabled, required models are configured, and the lesson scope includes the right folders.
Trace appears in the wrong project
Check the project_name passed to SovaraClient(...).
An LLM or supported framework tool call is missing
Confirm the call executes before the trace(...) context exits.
A custom operation is missing
Wrap its shared execution boundary with trace.
Threaded work attaches to the wrong trace
Submit sovara_client.with_context(fn) to the executor.
Logs mix between concurrent traces
Set capture_logs=False on concurrent top-level traces.
Recording is unavailable
Install the CLI and sign in with sovara login; the
SDK records to that server. On a headless host, set base_url and configure
api_key or SOVARA_API_KEY; see the
API reference.An unreachable server may let your agent continue without recording. Check the
trace ID before logging:
with sovara_client.trace("answer-question") as trace_id: answer = run_agent(question) if trace_id is not None: sovara_client.log(trace_id=trace_id, trace_output=answer)
Explicit calls such as log() raise RecordingError when the server fails. Catch it
where the agent must keep running. See Errors.
Missing custom steps
Call sovara.auto_instrument() before creating provider clients and tools. Framework tools
need their integration, for example sovara_openai_agents.instrument()
with the supported openai-agents>=0.13.6,<0.14 version installed by the integration.
Add @trace only to operations that are not already recorded:
from sovara import trace@tracedef retrieve_context(question: str) -> list[str]: return vector_search(question)
Keep agent work inside trace() and await tasks and streams before leaving it.
Use with_context() when passing work to another thread.Declare conversation turns with turn(); they are not created automatically.
Do not nest turns in the same trace or use a different client inside it.
See the usage guide.
{"docsConfig":{"theme":"aspen","$schema":"https://mintlify.com/docs.json","name":"Sovara","colors":{"primary":"#0E6B46","light":"#0E6B46","dark":"#0E6B46"},"logo":{"light":"https://mintcdn.com/sovaralabs/GrI0CPC3j94mST1A/assets/brand/full-logo-dark-green.svg?fit=max\u0026auto=format\u0026n=GrI0CPC3j94mST1A\u0026q=85\u0026s=4c4ceb88f1fc51e13d63b23d8d0d175d","dark":"https://mintcdn.com/sovaralabs/RStURBIEQ5vYmecw/assets/brand/full-logo-light-green.svg?fit=max\u0026auto=format\u0026n=RStURBIEQ5vYmecw\u0026q=85\u0026s=4701c8b788a7c1c846b1836a7f73d47f","href":"https://sovara-labs.com"},"favicon":{"light":"https://mintcdn.com/sovaralabs/uhTedr_9uhY39SOP/assets/brand/favicon-green.png?fit=max\u0026auto=format\u0026n=uhTedr_9uhY39SOP\u0026q=85\u0026s=9247a8530275edc273ea5c073c11f632","dark":"https://mintcdn.com/sovaralabs/uhTedr_9uhY39SOP/assets/brand/favicon-green.png?fit=max\u0026auto=format\u0026n=uhTedr_9uhY39SOP\u0026q=85\u0026s=9247a8530275edc273ea5c073c11f632"},"appearance":{"default":"light","strict":true},"navbar":{"primary":{"type":"button","label":"Book a demo","href":"mailto:[email protected]?subject=Book%20a%20Sovara%20demo"}},"footer":{"socials":{"github":"https://github.com/SovaraLabs","discord":"https://discord.gg/fjsNSa6TAh"},"links":[{"header":"Legal","items":[{"label":"Privacy Policy","href":"https://sovara-labs.com/legal/privacy-policy"}]}]},"fonts":{"family":"Inter"},"icons":{"library":"lucide"},"styling":{"eyebrows":"section","codeblocks":{"theme":{"light":"github-light","dark":"github-dark"}},"latex":false},"contextual":{"options":["copy","view","chatgpt","claude"],"display":"header"},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"sovaralabs","hasAudioNarration":false,"actualSubdomain":"sovaralabs","customDomains":["docs.sovara-labs.com"],"gitSource":{"type":"github","owner":"sovaralabs","repo":"sovara","deployBranch":"docs","contentDirectory":"docs","isPrivate":true,"mountPath":"","label":"","_id":"6aeb00ce6996bbb65a8506d5"},"entitlements":{"AI_CHAT":{"status":"DISABLED"}},"buildId":"6afc5b77f1815dc4b12ff70f","clientVersion":"0.0.4205","searchFilterCounts":[{"language":"default","tag":"User Guide","count":20},{"language":"default","tag":"CLI","count":15},{"language":"default","tag":"SDKs","count":10},{"language":"default","tag":"Core workflows","count":8},{"language":"default","tag":"Get started","count":7},{"language":"default","tag":"MCP","count":6},{"language":"default","tag":"Integrations","count":5},{"language":"default","tag":"Annotations","count":4},{"language":"default","tag":"Reference","count":4},{"language":"default","tag":"Python","count":4}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"starter-pricing","enabled":true,"variant":{"name":"treatment","enabled":true,"payload":{"type":"string","value":"treatment"},"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"wildcard-email-auth","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[{"filePath":"style.css","content":".nav-logo{height:2rem!important}#navbar .relative>.flex.items-center.h-14{height:4rem!important}#navbar a:has(.nav-logo){display:inline-flex;align-items:center;min-height:3rem}button[data-component-name=\"theme-toggle\"]>svg:first-child{display:none!important;color:rgb(75 85 99)}button[data-component-name=\"theme-toggle\"]>svg.lucide-moon{display:block!important;color:rgb(75 85 99)}.nav-tabs a[data-active=\"true\"]:hover{color:rgb(31 41 55)!important}.dark .nav-tabs a[data-active=\"true\"]:hover{color:rgb(229 231 235)!important}.dark button[data-component-name=\"theme-toggle\"]>svg:first-child{display:block!important;color:rgb(209 213 219)}.dark button[data-component-name=\"theme-toggle\"]>svg.lucide-moon{display:none!important}#sidebar-content li[data-active=\"true\"]>a,#sidebar li[data-active=\"true\"]>a{background-color:transparent!important}#sidebar-content li[data-active=\"true\"]>a:hover,#sidebar li[data-active=\"true\"]>a:hover{background-color:transparent!important}.quickstart-screenshot{width:100%;margin:1.25rem 0}.docs-screenshot{width:100%;margin:1.25rem 0}.docs-screenshot-dark{display:none}.dark .docs-screenshot-light{display:none}.dark .docs-screenshot-dark{display:block}.philosophy-graphic-wrap{display:flex;justify-content:center;margin:1.5rem 0 2.5rem}.philosophy-graphic{width:min(100%, 36rem)}.philosophy-graphic-dark{display:none}.dark .philosophy-graphic-light{display:none}.dark .philosophy-graphic-dark{display:block}.install-downloads{margin-top:2rem;margin-bottom:2rem}.install-downloads-header{display:flex;align-items:center;justify-content:flex-end;gap:1rem;margin-bottom:0.75rem}.install-downloads-header span{flex:none;color:rgb(82 82 82);font-size:0.875rem}.dark .install-downloads-header span{color:rgb(163 163 163)}.install-download-grid{display:grid;grid-template-columns:repeat(3, minmax(0, 1fr));gap:0.875rem}.install-download-card{display:flex;min-width:0;min-height:13rem;flex-direction:column;border:1px solid rgb(229 229 229);border-radius:0.5rem;padding:1.125rem;background:rgb(255 255 255)}.dark .install-download-card{border-color:rgb(38 38 38);background:rgb(13 13 11)}.install-os-mark{display:flex;align-items:center;height:2.75rem;margin-bottom:0.875rem}.install-os-logo{width:auto;max-width:3rem;max-height:2.5rem}.install-os-logo-dark{display:none}.dark .install-os-logo-light{display:none}.dark .install-os-logo-dark{display:block}.install-card-title{margin:0;color:rgb(23 23 23);font-size:1.125rem;font-weight:700;line-height:1.4}.dark .install-card-title{color:rgb(245 245 245)}.install-download-card p{margin:0.35rem 0 0.9rem;color:rgb(82 82 82);font-size:0.95rem;line-height:1.55}.dark .install-download-card p{color:rgb(163 163 163)}.install-download-link{display:inline-flex;align-items:center;width:fit-content;max-width:100%;padding:0.125rem 0;color:rgb(13 132 76)!important;font-size:0.875rem;font-weight:600;line-height:1.35;text-align:left;text-decoration:none!important}.dark .install-download-link{color:rgb(52 211 153)!important}.install-download-link+.install-download-link{margin-top:0.35rem}.install-download-link>*{margin:0!important;color:inherit!important;font:inherit!important;line-height:inherit!important}.install-download-link:hover{color:rgb(9 105 61)!important;text-decoration:underline!important;text-underline-offset:0.18em}body:has(#content[data-page-href*=\"/sdks/index\"]) #sidebar-content,body:has(#content[data-page-href*=\"/sdks/index\"]) #content-side-layout,body:has(#content[data-page-href*=\"/sdks/index\"]) #header{display:none!important}body:has(#content[data-page-href*=\"/sdks/index\"]) #content-container{display:block!important;max-width:64rem!important;padding:4rem 1.5rem 0!important}body:has(#content[data-page-href*=\"/sdks/index\"]) #content-area{width:100%!important;max-width:none!important}body:has(#content[data-page-href*=\"/sdks/index\"]) #content{margin-top:0!important;margin-bottom:8rem!important}body:has(#content[data-page-href*=\"/sdks/python/\"]) #navigation-items .my-2:has(a[href^=\"/sdks/typescript/\"]),body:has(#content[data-page-href*=\"/sdks/python/\"]) #navigation-items .px-1.py-3:has(+.my-2 a[href^=\"/sdks/typescript/\"]),body:has(#content[data-page-href*=\"/sdks/typescript/\"]) #navigation-items .my-2:has(a[href^=\"/sdks/python/\"]),body:has(#content[data-page-href*=\"/sdks/typescript/\"]) #navigation-items .px-1.py-3:has(+.my-2 a[href^=\"/sdks/python/\"]){display:none!important}body:has(#content[data-page-href*=\"/sdks/python/\"]) #header .eyebrow,body:has(#content[data-page-href*=\"/sdks/typescript/\"]) #header .eyebrow,body:has(#content[data-page-href*=\"/sdks/python/\"]) #navigation-items .text-sm>.mt-6>.sidebar-group-header,body:has(#content[data-page-href*=\"/sdks/typescript/\"]) #navigation-items .text-sm>.mt-6>.sidebar-group-header{display:none!important}body:has(#content[data-page-href*=\"/sdks/python/\"]) #navigation-items li[id=\"/sdks/python/quickstart\"] a span,body:has(#content[data-page-href*=\"/sdks/typescript/\"]) #navigation-items li[id=\"/sdks/typescript/quickstart\"] a span{font-size:0!important}body:has(#content[data-page-href*=\"/sdks/python/\"]) #navigation-items li[id=\"/sdks/python/quickstart\"] a span::after,body:has(#content[data-page-href*=\"/sdks/typescript/\"]) #navigation-items li[id=\"/sdks/typescript/quickstart\"] a span::after{content:\"Quickstart\";font-size:0.875rem;line-height:1.5rem}body:has(#content[data-page-href*=\"/sdks/\"]) .nav-dropdown-content a[data-dropdown-item=\"SDKs\"]{display:none!important}.sdk-overview{margin:0 auto 2rem;max-width:56rem}.sdk-overview h1{margin:0 0 0.75rem;color:rgb(17 24 39);font-size:2.25rem;font-weight:700;line-height:1.15}.dark .sdk-overview h1{color:rgb(245 245 245)}.sdk-overview p{margin:0;color:rgb(107 114 128);font-size:1.125rem;line-height:1.6}.dark .sdk-overview p{color:rgb(163 163 163)}.sdk-card-grid{display:grid;grid-template-columns:repeat(3, minmax(0, 1fr));gap:1rem;max-width:56rem;margin:2.5rem auto 0}.sdk-card{display:block;min-height:6.625rem;padding:1.25rem 1.5rem 1.375rem;border:1px solid rgb(229 229 229);border-radius:0.5rem;background:rgb(255 255 255);color:inherit!important;text-decoration:none!important}.dark .sdk-card{border-color:rgb(38 38 38);background:rgb(13 13 11)}.sdk-card:hover{border-color:rgb(14 107 70)}.sdk-card-logo{display:block;width:1.75rem;height:1.75rem;margin-bottom:1rem;background-position:center;background-repeat:no-repeat;background-size:contain}.sdk-card-logo-typescript{background-image:url(\"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjggMTI4Ij48cGF0aCBmaWxsPSIjZmZmIiBkPSJNMjIuNjcgNDdoOTkuNjd2NzMuNjdIMjIuNjd6Ii8+PHBhdGggZGF0YS1uYW1lPSJvcmlnaW5hbCIgZmlsbD0iIzAwN2FjYyIgZD0iTTEuNSA2My45MXY2Mi41aDEyNXYtMTI1SDEuNXptMTAwLjczLTVhMTUuNTYgMTUuNTYgMCAwMTcuODIgNC41IDIwLjU4IDIwLjU4IDAgMDEzIDRjMCAuMTYtNS40IDMuODEtOC42OSA1Ljg1LS4xMi4wOC0uNi0uNDQtMS4xMy0xLjIzYTcuMDkgNy4wOSAwIDAwLTUuODctMy41M2MtMy43OS0uMjYtNi4yMyAxLjczLTYuMjEgNWE0LjU4IDQuNTggMCAwMC41NCAyLjM0Yy44MyAxLjczIDIuMzggMi43NiA3LjI0IDQuODYgOC45NSAzLjg1IDEyLjc4IDYuMzkgMTUuMTYgMTAgMi42NiA0IDMuMjUgMTAuNDYgMS40NSAxNS4yNC0yIDUuMi02LjkgOC43My0xMy44MyA5LjlhMzguMzIgMzguMzIgMCAwMS05LjUyLS4xIDIzIDIzIDAgMDEtMTIuNzItNi42M2MtMS4xNS0xLjI3LTMuMzktNC41OC0zLjI1LTQuODJhOS4zNCA5LjM0IDAgMDExLjE1LS43M0w4MiAxMDFsMy41OS0yLjA4Ljc1IDEuMTFhMTYuNzggMTYuNzggMCAwMDQuNzQgNC41NGM0IDIuMSA5LjQ2IDEuODEgMTIuMTYtLjYyYTUuNDMgNS40MyAwIDAwLjY5LTYuOTJjLTEtMS4zOS0zLTIuNTYtOC41OS01LTYuNDUtMi43OC05LjIzLTQuNS0xMS43Ny03LjI0YTE2LjQ4IDE2LjQ4IDAgMDEtMy40My02LjI1IDI1IDI1IDAgMDEtLjIyLThjMS4zMy02LjIzIDYtMTAuNTggMTIuODItMTEuODdhMzEuNjYgMzEuNjYgMCAwMTkuNDkuMjZ6bS0yOS4zNCA1LjI0djUuMTJINTYuNjZ2NDYuMjNINDUuMTVWNjkuMjZIMjguODh2LTVhNDkuMTkgNDkuMTkgMCAwMS4xMi01LjE3QzI5LjA4IDU5IDM5IDU5IDUxIDU5aDIxLjgzeiIvPjwvc3ZnPg==\")}.sdk-card-logo-python{background-image:url(\"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjggMTI4Ij48bGluZWFyR3JhZGllbnQgaWQ9InB5dGhvbi1vcmlnaW5hbC1hIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9IjcwLjI1MiIgeTE9IjEyMzcuNDc2IiB4Mj0iMTcwLjY1OSIgeTI9IjExNTEuMDg5IiBncmFkaWVudFRyYW5zZm9ybT0ibWF0cml4KC41NjMgMCAwIC0uNTY4IC0yOS4yMTUgNzA3LjgxNykiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzVBOUZENCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzMwNjk5OCIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJweXRob24tb3JpZ2luYWwtYiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiIHgxPSIyMDkuNDc0IiB5MT0iMTA5OC44MTEiIHgyPSIxNzMuNjIiIHkyPSIxMTQ5LjUzNyIgZ3JhZGllbnRUcmFuc2Zvcm09Im1hdHJpeCguNTYzIDAgMCAtLjU2OCAtMjkuMjE1IDcwNy44MTcpIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNGRkQ0M0IiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRkU4NzMiLz48L2xpbmVhckdyYWRpZW50PjxwYXRoIGZpbGw9InVybCgjcHl0aG9uLW9yaWdpbmFsLWEpIiBkPSJNNjMuMzkxIDEuOTg4Yy00LjIyMi4wMi04LjI1Mi4zNzktMTEuOCAxLjAwNy0xMC40NSAxLjg0Ni0xMi4zNDYgNS43MS0xMi4zNDYgMTIuODM3djkuNDExaDI0LjY5M3YzLjEzN0gyOS45NzdjLTcuMTc2IDAtMTMuNDYgNC4zMTMtMTUuNDI2IDEyLjUyMS0yLjI2OCA5LjQwNS0yLjM2OCAxNS4yNzUgMCAyNS4wOTYgMS43NTUgNy4zMTEgNS45NDcgMTIuNTE5IDEzLjEyNCAxMi41MTloOC40OTFWNjcuMjM0YzAtOC4xNTEgNy4wNTEtMTUuMzQgMTUuNDI2LTE1LjM0aDI0LjY2NWM2Ljg2NiAwIDEyLjM0Ni01LjY1NCAxMi4zNDYtMTIuNTQ4VjE1LjgzM2MwLTYuNjkzLTUuNjQ2LTExLjcyLTEyLjM0Ni0xMi44MzctNC4yNDQtLjcwNi04LjY0NS0xLjAyNy0xMi44NjYtMS4wMDh6TTUwLjAzNyA5LjU1N2MyLjU1IDAgNC42MzQgMi4xMTcgNC42MzQgNC43MjEgMCAyLjU5My0yLjA4MyA0LjY5LTQuNjM0IDQuNjktMi41NiAwLTQuNjMzLTIuMDk3LTQuNjMzLTQuNjktLjAwMS0yLjYwNCAyLjA3My00LjcyMSA0LjYzMy00LjcyMXoiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAgMTAuMjYpIi8+PHBhdGggZmlsbD0idXJsKCNweXRob24tb3JpZ2luYWwtYikiIGQ9Ik05MS42ODIgMjguMzh2MTAuOTY2YzAgOC41LTcuMjA4IDE1LjY1NS0xNS40MjYgMTUuNjU1SDUxLjU5MWMtNi43NTYgMC0xMi4zNDYgNS43ODMtMTIuMzQ2IDEyLjU0OXYyMy41MTVjMCA2LjY5MSA1LjgxOCAxMC42MjggMTIuMzQ2IDEyLjU0NyA3LjgxNiAyLjI5NyAxNS4zMTIgMi43MTMgMjQuNjY1IDAgNi4yMTYtMS44MDEgMTIuMzQ2LTUuNDIzIDEyLjM0Ni0xMi41NDd2LTkuNDEySDYzLjkzOHYtMy4xMzhoMzcuMDEyYzcuMTc2IDAgOS44NTItNS4wMDUgMTIuMzQ4LTEyLjUxOSAyLjU3OC03LjczNSAyLjQ2Ny0xNS4xNzQgMC0yNS4wOTYtMS43NzQtNy4xNDUtNS4xNjEtMTIuNTIxLTEyLjM0OC0xMi41MjFoLTkuMjY4ek03Ny44MDkgODcuOTI3YzIuNTYxIDAgNC42MzQgMi4wOTcgNC42MzQgNC42OTIgMCAyLjYwMi0yLjA3NCA0LjcxOS00LjYzNCA0LjcxOS0yLjU1IDAtNC42MzMtMi4xMTctNC42MzMtNC43MTkgMC0yLjU5NSAyLjA4My00LjY5MiA0LjYzMy00LjY5MnoiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAgMTAuMjYpIi8+PHJhZGlhbEdyYWRpZW50IGlkPSJweXRob24tb3JpZ2luYWwtYyIgY3g9IjE4MjUuNjc4IiBjeT0iNDQ0LjQ1IiByPSIyNi43NDMiIGdyYWRpZW50VHJhbnNmb3JtPSJtYXRyaXgoMCAtLjI0IC0xLjA1NSAwIDUzMi45NzkgNTU3LjU3NikiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNCOEI4QjgiIHN0b3Atb3BhY2l0eT0iLjQ5OCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzdGN0Y3RiIgc3RvcC1vcGFjaXR5PSIwIi8+PC9yYWRpYWxHcmFkaWVudD48cGF0aCBvcGFjaXR5PSIuNDQ0IiBmaWxsPSJ1cmwoI3B5dGhvbi1vcmlnaW5hbC1jKSIgZD0iTTk3LjMwOSAxMTkuNTk3YzAgMy41NDMtMTQuODE2IDYuNDE2LTMzLjA5MSA2LjQxNi0xOC4yNzYgMC0zMy4wOTItMi44NzMtMzMuMDkyLTYuNDE2IDAtMy41NDQgMTQuODE1LTYuNDE3IDMzLjA5Mi02LjQxNyAxOC4yNzUgMCAzMy4wOTEgMi44NzIgMzMuMDkxIDYuNDE3eiIvPjwvc3ZnPgo=\")}.sdk-card-title{color:rgb(23 23 23);font-size:1.125rem;font-weight:700;line-height:1.4}.dark .sdk-card-title{color:rgb(245 245 245)}.sdk-card p{margin:0.4rem 0 0;color:rgb(82 82 82);font-size:0.95rem;line-height:1.55}.dark .sdk-card p{color:rgb(163 163 163)}@media (max-width: 720px){.sdk-card-grid{grid-template-columns:1fr}}.dark .install-download-link:hover{color:rgb(110 231 183)!important}@media (max-width: 768px){.install-downloads-header{align-items:flex-start;flex-direction:column}.install-download-grid{grid-template-columns:1fr}.install-download-card{min-height:0}}"}],"page":{"pagePath":"sdks/python/troubleshooting","slug":"/sdks/python/troubleshooting","pageMetadata":{"title":"Troubleshooting","description":"Diagnose missing Python traces, steps, project assignment, and context.","href":"/sdks/python/troubleshooting"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Diagnose missing Python traces, steps, project assignment, and context.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,p:`p`,pre:`pre`,span:`span`,tbody:`tbody`,td:`td`,th:`th`,thead:`thead`,tr:`tr`,..._provideComponents(),...props.components},{CodeBlock,Heading,Icon,Table}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Icon)_missingMdxReference(`Icon`,true);if(!Table)_missingMdxReference(`Table`,true);return _jsxs(_Fragment,{children:[_jsx(`script`,{src:`/assets/sdk-nav.js`}),`\n`,_jsx(Heading,{level:`2`,id:`common-checks`,children:`Common checks`}),`\n`,_jsxs(Table,{children:[_jsx(_components.thead,{children:_jsxs(_components.tr,{children:[_jsx(_components.th,{children:`Symptom`}),_jsx(_components.th,{children:`Check`})]})}),_jsxs(_components.tbody,{children:[_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`No trace appears`}),_jsxs(_components.td,{children:[`Confirm the entrypoint enters `,_jsx(_components.code,{children:`sovara_client.trace(...)`}),`. Check the terminal for a Sovara warning.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`A trace appears without model or tool steps`}),_jsxs(_components.td,{children:[`Call `,_jsx(_components.code,{children:`sovara.auto_instrument()`}),` once at startup, before creating provider clients.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:_jsx(_components.code,{children:`CompatibilityError`})}),_jsx(_components.td,{children:`The Sovara server is older than the SDK. Update the Sovara server.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`An evaluation sample is missing from Traces`}),_jsxs(_components.td,{children:[`Look in `,_jsxs(`strong`,{children:[_jsx(Icon,{icon:`chart-no-axes-column`,size:14}),` Evaluations`]}),`; the main Traces view excludes evaluation-owned samples.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Lessons are missing`}),_jsx(_components.td,{children:`Check that the key allows lessons, the proposal was applied, automatic injection is enabled, required models are configured, and the lesson scope includes the right folders.`})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Trace appears in the wrong project`}),_jsxs(_components.td,{children:[`Check the `,_jsx(_components.code,{children:`project_name`}),` passed to `,_jsx(_components.code,{children:`SovaraClient(...)`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`An LLM or supported framework tool call is missing`}),_jsxs(_components.td,{children:[`Confirm the call executes before the `,_jsx(_components.code,{children:`trace(...)`}),` context exits.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`A custom operation is missing`}),_jsxs(_components.td,{children:[`Wrap its shared execution boundary with `,_jsx(_components.code,{children:`trace`}),`.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Threaded work attaches to the wrong trace`}),_jsxs(_components.td,{children:[`Submit `,_jsx(_components.code,{children:`sovara_client.with_context(fn)`}),` to the executor.`]})]}),_jsxs(_components.tr,{children:[_jsx(_components.td,{children:`Logs mix between concurrent traces`}),_jsxs(_components.td,{children:[`Set `,_jsx(_components.code,{children:`capture_logs=False`}),` on concurrent top-level traces.`]})]})]})]}),`\n`,_jsx(Heading,{level:`2`,id:`recording-is-unavailable`,children:`Recording is unavailable`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.a,{href:`/cli/install`,children:`Install the CLI`}),` and sign in with `,_jsx(_components.code,{children:`sovara login`}),`; the\nSDK records to that server. On a headless host, set `,_jsx(_components.code,{children:`base_url`}),` and configure\n`,_jsx(_components.code,{children:`api_key`}),` or `,_jsx(_components.code,{children:`SOVARA_API_KEY`}),`; see the\n`,_jsx(_components.a,{href:`/sdks/python/api-reference`,children:`API reference`}),`.`]}),`\n`,_jsx(_components.p,{children:`An unreachable server may let your agent continue without recording. Check the\ntrace ID before logging:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`4`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light github-dark`,style:{backgroundColor:`#fff`,\"--shiki-dark-bg\":`#24292e`,color:`#24292e`,\"--shiki-dark\":`#e1e4e8`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`4`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`with`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` sovara_client.trace(`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`\"answer-question\"`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`) `}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`as`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` trace_id:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` answer `}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`=`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` run_agent(question)`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` if`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` trace_id `}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`is`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` not`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` None`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` sovara_client.log(`}),_jsx(_components.span,{style:{color:`#E36209`,\"--shiki-dark\":`#FFAB70`},children:`trace_id`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`=`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`trace_id, `}),_jsx(_components.span,{style:{color:`#E36209`,\"--shiki-dark\":`#FFAB70`},children:`trace_output`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`=`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`answer)`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Explicit calls such as `,_jsx(_components.code,{children:`log()`}),` raise `,_jsx(_components.code,{children:`RecordingError`}),` when the server fails. Catch it\nwhere the agent must keep running. See `,_jsx(_components.a,{href:`/sdks/python/api-reference#errors`,children:`Errors`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`missing-custom-steps`,children:`Missing custom steps`}),`\n`,_jsxs(_components.p,{children:[`Call `,_jsx(_components.code,{children:`sovara.auto_instrument()`}),` before creating provider clients and tools. Framework tools\nneed their `,_jsx(_components.a,{href:`/integrations/overview`,children:`integration`}),`, for example `,_jsx(_components.code,{children:`sovara_openai_agents.instrument()`}),`\nwith the supported `,_jsx(_components.code,{children:`openai-agents>=0.13.6,\u003c0.14`}),` version installed by the integration.\nAdd `,_jsx(_components.code,{children:`@trace`}),` only to operations that are not already recorded:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`5`,language:`python`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light github-dark`,style:{backgroundColor:`#fff`,\"--shiki-dark-bg\":`#24292e`,color:`#24292e`,\"--shiki-dark\":`#e1e4e8`},language:`python`,children:_jsxs(_components.code,{language:`python`,numberOfLines:`5`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`from`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` sovara `}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`import`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` trace`})]}),`\n`,_jsx(_components.span,{className:`line`}),`\n`,_jsx(_components.span,{className:`line`,children:_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`@trace`})}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`def`}),_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:` retrieve_context`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`(question: `}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:`str`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`) -> list[`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:`str`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:`]:`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` return`}),_jsx(_components.span,{style:{color:`#24292E`,\"--shiki-dark\":`#E1E4E8`},children:` vector_search(question)`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`inspect-what-was-recorded`,children:`Inspect what was recorded`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`3`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes github-light github-dark`,style:{backgroundColor:`#fff`,\"--shiki-dark-bg\":`#24292e`,color:`#24292e`,\"--shiki-dark\":`#e1e4e8`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`3`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`sovara`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` probe`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` \u003c`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`trace-i`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`d`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`>`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`sovara`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` probe`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` \u003c`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`trace-i`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`d`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`>`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` --step`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` \u003c`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`step-re`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`f`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`>`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` --preview`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`sovara`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:` logs`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:` \u003c`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`trace-i`}),_jsx(_components.span,{style:{color:`#032F62`,\"--shiki-dark\":`#9ECBFF`},children:`d`}),_jsx(_components.span,{style:{color:`#D73A49`,\"--shiki-dark\":`#F97583`},children:`>`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` --tail`}),_jsx(_components.span,{style:{color:`#005CC5`,\"--shiki-dark\":`#79B8FF`},children:` 40`})]}),`\n`]})})}),`\n`,_jsxs(_components.p,{children:[`Use step references shown by `,_jsx(_components.code,{children:`probe`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`traces-and-turns`,children:`Traces and turns`}),`\n`,_jsxs(_components.p,{children:[`Keep agent work inside `,_jsx(_components.code,{children:`trace()`}),` and await tasks and streams before leaving it.\nUse `,_jsx(_components.code,{children:`with_context()`}),` when passing work to another thread.`]}),`\n`,_jsxs(_components.p,{children:[`Declare conversation turns with `,_jsx(_components.code,{children:`turn()`}),`; they are not created automatically.\nDo not nest turns in the same trace or use a different client inside it.\nSee `,_jsx(_components.a,{href:`/sdks/python/use-the-sdk#explicit-conversation-turns`,children:`the usage guide`}),`.`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"codeStyling":{"theme":{"light":"github-light","dark":"github-dark"}},"config":{},"pageMetadata":{"title":"Troubleshooting","description":"Diagnose missing Python traces, steps, project assignment, and context.","href":"/sdks/python/troubleshooting"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"Common checks","slug":"common-checks","depth":2,"children":[]},{"title":"Recording is unavailable","slug":"recording-is-unavailable","depth":2,"children":[]},{"title":"Missing custom steps","slug":"missing-custom-steps","depth":2,"children":[]},{"title":"Inspect what was recorded","slug":"inspect-what-was-recorded","depth":2,"children":[]},{"title":"Traces and turns","slug":"traces-and-turns","depth":2,"children":[]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/sovaralabs/be6ea1eecd1f39b0/assets/sdk-nav.js"],"subdomain":"sovaralabs","siteName":"Sovara","title":"Troubleshooting - Sovara","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-15T16:41:57.766Z","originalFileLocation":"sdks/python/troubleshooting.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=\"light\";if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"light\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Diagnose missing Python traces, steps, project assignment, and context.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Sovara\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Troubleshooting - Sovara\">\u003cmeta data-mint-head property=\"og:description\" content=\"Diagnose missing Python traces, steps, project assignment, and context.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Sovara\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.sovara-labs.com/sdks/python/troubleshooting\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://sovaralabs.mintlify.site/_mintlify/api/og/v2?division=Use+the+SDK\u0026amp;title=Troubleshooting\u0026amp;description=Diagnose+missing+Python+traces%2C+steps%2C+project+assignment%2C+and+context.\u0026amp;theme=64162267d856fd746d4a9988\u0026amp;signature=7d484e8b747b80cd74197209245f79b681156d8f2e9922aac3d65a4924406258\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Troubleshooting - Sovara\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Diagnose missing Python traces, steps, project assignment, and context.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://sovaralabs.mintlify.site/_mintlify/api/og/v2?division=Use+the+SDK\u0026amp;title=Troubleshooting\u0026amp;description=Diagnose+missing+Python+traces%2C+steps%2C+project+assignment%2C+and+context.\u0026amp;theme=64162267d856fd746d4a9988\u0026amp;signature=7d484e8b747b80cd74197209245f79b681156d8f2e9922aac3d65a4924406258\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/sovaralabs/kYx3Jt_pxVtI7LkU/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Sovara\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#0E6B46\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.sovara-labs.com/sdks/python/troubleshooting\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/sdks/python/troubleshooting.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.sovara-labs.com/#organization\",\"name\":\"Sovara\",\"url\":\"https://docs.sovara-labs.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/sovaralabs/GrI0CPC3j94mST1A/assets/brand/full-logo-dark-green.svg?fit=max\u0026auto=format\u0026n=GrI0CPC3j94mST1A\u0026q=85\u0026s=4c4ceb88f1fc51e13d63b23d8d0d175d\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.sovara-labs.com#website\",\"name\":\"Sovara\",\"url\":\"https://docs.sovara-labs.com\",\"publisher\":{\"@id\":\"https://docs.sovara-labs.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.sovara-labs.com/sdks/python/troubleshooting#webpage\",\"url\":\"https://docs.sovara-labs.com/sdks/python/troubleshooting\",\"name\":\"Troubleshooting\",\"description\":\"Diagnose missing Python traces, steps, project assignment, and context.\",\"dateModified\":\"2026-11-15T16:41:57.766Z\",\"isPartOf\":{\"@id\":\"https://docs.sovara-labs.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.sovara-labs.com/sdks/python/troubleshooting#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.sovara-labs.com/sdks/python/troubleshooting#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Use the SDK\",\"item\":\"https://docs.sovara-labs.com/sdks/python/use-the-sdk\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Troubleshooting\",\"item\":\"https://docs.sovara-labs.com/sdks/python/troubleshooting\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://docs.sovara-labs.com/sdks/python/troubleshooting#article\",\"headline\":\"Troubleshooting\",\"name\":\"Troubleshooting\",\"description\":\"Diagnose missing Python traces, steps, project assignment, and context.\",\"url\":\"https://docs.sovara-labs.com/sdks/python/troubleshooting\",\"mainEntityOfPage\":{\"@id\":\"https://docs.sovara-labs.com/sdks/python/troubleshooting#webpage\"},\"dateModified\":\"2026-11-15T16:41:57.766Z\",\"publisher\":{\"@id\":\"https://docs.sovara-labs.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.sovara-labs.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Sovara\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Sovara\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/sdks/python/troubleshooting.md","siteName":"Sovara","nav":{"global":null,"tabs":[{"tab":"User Guide","icon":"book-open","pages":[{"title":"User Guide","href":"/get-started/installation"}]},{"tab":"SDKs","icon":"blocks","dropdowns":[{"dropdown":"SDKs","icon":"blocks","pages":[{"title":"SDKs","href":"/sdks"}]},{"dropdown":"Python","icon":"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjggMTI4Ij48bGluZWFyR3JhZGllbnQgaWQ9InB5dGhvbi1vcmlnaW5hbC1hIiBncmFkaWVudFVuaXRzPSJ1c2VyU3BhY2VPblVzZSIgeDE9IjcwLjI1MiIgeTE9IjEyMzcuNDc2IiB4Mj0iMTcwLjY1OSIgeTI9IjExNTEuMDg5IiBncmFkaWVudFRyYW5zZm9ybT0ibWF0cml4KC41NjMgMCAwIC0uNTY4IC0yOS4yMTUgNzA3LjgxNykiPjxzdG9wIG9mZnNldD0iMCIgc3RvcC1jb2xvcj0iIzVBOUZENCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzMwNjk5OCIvPjwvbGluZWFyR3JhZGllbnQ+PGxpbmVhckdyYWRpZW50IGlkPSJweXRob24tb3JpZ2luYWwtYiIgZ3JhZGllbnRVbml0cz0idXNlclNwYWNlT25Vc2UiIHgxPSIyMDkuNDc0IiB5MT0iMTA5OC44MTEiIHgyPSIxNzMuNjIiIHkyPSIxMTQ5LjUzNyIgZ3JhZGllbnRUcmFuc2Zvcm09Im1hdHJpeCguNTYzIDAgMCAtLjU2OCAtMjkuMjE1IDcwNy44MTcpIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNGRkQ0M0IiLz48c3RvcCBvZmZzZXQ9IjEiIHN0b3AtY29sb3I9IiNGRkU4NzMiLz48L2xpbmVhckdyYWRpZW50PjxwYXRoIGZpbGw9InVybCgjcHl0aG9uLW9yaWdpbmFsLWEpIiBkPSJNNjMuMzkxIDEuOTg4Yy00LjIyMi4wMi04LjI1Mi4zNzktMTEuOCAxLjAwNy0xMC40NSAxLjg0Ni0xMi4zNDYgNS43MS0xMi4zNDYgMTIuODM3djkuNDExaDI0LjY5M3YzLjEzN0gyOS45NzdjLTcuMTc2IDAtMTMuNDYgNC4zMTMtMTUuNDI2IDEyLjUyMS0yLjI2OCA5LjQwNS0yLjM2OCAxNS4yNzUgMCAyNS4wOTYgMS43NTUgNy4zMTEgNS45NDcgMTIuNTE5IDEzLjEyNCAxMi41MTloOC40OTFWNjcuMjM0YzAtOC4xNTEgNy4wNTEtMTUuMzQgMTUuNDI2LTE1LjM0aDI0LjY2NWM2Ljg2NiAwIDEyLjM0Ni01LjY1NCAxMi4zNDYtMTIuNTQ4VjE1LjgzM2MwLTYuNjkzLTUuNjQ2LTExLjcyLTEyLjM0Ni0xMi44MzctNC4yNDQtLjcwNi04LjY0NS0xLjAyNy0xMi44NjYtMS4wMDh6TTUwLjAzNyA5LjU1N2MyLjU1IDAgNC42MzQgMi4xMTcgNC42MzQgNC43MjEgMCAyLjU5My0yLjA4MyA0LjY5LTQuNjM0IDQuNjktMi41NiAwLTQuNjMzLTIuMDk3LTQuNjMzLTQuNjktLjAwMS0yLjYwNCAyLjA3My00LjcyMSA0LjYzMy00LjcyMXoiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAgMTAuMjYpIi8+PHBhdGggZmlsbD0idXJsKCNweXRob24tb3JpZ2luYWwtYikiIGQ9Ik05MS42ODIgMjguMzh2MTAuOTY2YzAgOC41LTcuMjA4IDE1LjY1NS0xNS40MjYgMTUuNjU1SDUxLjU5MWMtNi43NTYgMC0xMi4zNDYgNS43ODMtMTIuMzQ2IDEyLjU0OXYyMy41MTVjMCA2LjY5MSA1LjgxOCAxMC42MjggMTIuMzQ2IDEyLjU0NyA3LjgxNiAyLjI5NyAxNS4zMTIgMi43MTMgMjQuNjY1IDAgNi4yMTYtMS44MDEgMTIuMzQ2LTUuNDIzIDEyLjM0Ni0xMi41NDd2LTkuNDEySDYzLjkzOHYtMy4xMzhoMzcuMDEyYzcuMTc2IDAgOS44NTItNS4wMDUgMTIuMzQ4LTEyLjUxOSAyLjU3OC03LjczNSAyLjQ2Ny0xNS4xNzQgMC0yNS4wOTYtMS43NzQtNy4xNDUtNS4xNjEtMTIuNTIxLTEyLjM0OC0xMi41MjFoLTkuMjY4ek03Ny44MDkgODcuOTI3YzIuNTYxIDAgNC42MzQgMi4wOTcgNC42MzQgNC42OTIgMCAyLjYwMi0yLjA3NCA0LjcxOS00LjYzNCA0LjcxOS0yLjU1IDAtNC42MzMtMi4xMTctNC42MzMtNC43MTkgMC0yLjU5NSAyLjA4My00LjY5MiA0LjYzMy00LjY5MnoiIHRyYW5zZm9ybT0idHJhbnNsYXRlKDAgMTAuMjYpIi8+PHJhZGlhbEdyYWRpZW50IGlkPSJweXRob24tb3JpZ2luYWwtYyIgY3g9IjE4MjUuNjc4IiBjeT0iNDQ0LjQ1IiByPSIyNi43NDMiIGdyYWRpZW50VHJhbnNmb3JtPSJtYXRyaXgoMCAtLjI0IC0xLjA1NSAwIDUzMi45NzkgNTU3LjU3NikiIGdyYWRpZW50VW5pdHM9InVzZXJTcGFjZU9uVXNlIj48c3RvcCBvZmZzZXQ9IjAiIHN0b3AtY29sb3I9IiNCOEI4QjgiIHN0b3Atb3BhY2l0eT0iLjQ5OCIvPjxzdG9wIG9mZnNldD0iMSIgc3RvcC1jb2xvcj0iIzdGN0Y3RiIgc3RvcC1vcGFjaXR5PSIwIi8+PC9yYWRpYWxHcmFkaWVudD48cGF0aCBvcGFjaXR5PSIuNDQ0IiBmaWxsPSJ1cmwoI3B5dGhvbi1vcmlnaW5hbC1jKSIgZD0iTTk3LjMwOSAxMTkuNTk3YzAgMy41NDMtMTQuODE2IDYuNDE2LTMzLjA5MSA2LjQxNi0xOC4yNzYgMC0zMy4wOTItMi44NzMtMzMuMDkyLTYuNDE2IDAtMy41NDQgMTQuODE1LTYuNDE3IDMzLjA5Mi02LjQxNyAxOC4yNzUgMCAzMy4wOTEgMi44NzIgMzMuMDkxIDYuNDE3eiIvPjwvc3ZnPgo=","groups":[{"group":"Get started","pages":[{"title":"Python SDK quickstart","href":"/sdks/python/quickstart"}]},{"group":"Use the SDK","icon":"code","pages":[{"title":"Use the SDK","description":"Understand project clients, traces, steps, subtraces, metadata, and lessons.","href":"/sdks/python/use-the-sdk"},{"title":"Troubleshooting","href":"/sdks/python/troubleshooting"}]},{"group":"Reference","icon":"file-text","pages":[{"title":"API reference","description":"The public Sovara Python SDK surface and exact client methods.","href":"/sdks/python/api-reference"}]}]},{"dropdown":"TypeScript","icon":"data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAxMjggMTI4Ij48cGF0aCBmaWxsPSIjZmZmIiBkPSJNMjIuNjcgNDdoOTkuNjd2NzMuNjdIMjIuNjd6Ii8+PHBhdGggZGF0YS1uYW1lPSJvcmlnaW5hbCIgZmlsbD0iIzAwN2FjYyIgZD0iTTEuNSA2My45MXY2Mi41aDEyNXYtMTI1SDEuNXptMTAwLjczLTVhMTUuNTYgMTUuNTYgMCAwMTcuODIgNC41IDIwLjU4IDIwLjU4IDAgMDEzIDRjMCAuMTYtNS40IDMuODEtOC42OSA1Ljg1LS4xMi4wOC0uNi0uNDQtMS4xMy0xLjIzYTcuMDkgNy4wOSAwIDAwLTUuODctMy41M2MtMy43OS0uMjYtNi4yMyAxLjczLTYuMjEgNWE0LjU4IDQuNTggMCAwMC41NCAyLjM0Yy44MyAxLjczIDIuMzggMi43NiA3LjI0IDQuODYgOC45NSAzLjg1IDEyLjc4IDYuMzkgMTUuMTYgMTAgMi42NiA0IDMuMjUgMTAuNDYgMS40NSAxNS4yNC0yIDUuMi02LjkgOC43My0xMy44MyA5LjlhMzguMzIgMzguMzIgMCAwMS05LjUyLS4xIDIzIDIzIDAgMDEtMTIuNzItNi42M2MtMS4xNS0xLjI3LTMuMzktNC41OC0zLjI1LTQuODJhOS4zNCA5LjM0IDAgMDExLjE1LS43M0w4MiAxMDFsMy41OS0yLjA4Ljc1IDEuMTFhMTYuNzggMTYuNzggMCAwMDQuNzQgNC41NGM0IDIuMSA5LjQ2IDEuODEgMTIuMTYtLjYyYTUuNDMgNS40MyAwIDAwLjY5LTYuOTJjLTEtMS4zOS0zLTIuNTYtOC41OS01LTYuNDUtMi43OC05LjIzLTQuNS0xMS43Ny03LjI0YTE2LjQ4IDE2LjQ4IDAgMDEtMy40My02LjI1IDI1IDI1IDAgMDEtLjIyLThjMS4zMy02LjIzIDYtMTAuNTggMTIuODItMTEuODdhMzEuNjYgMzEuNjYgMCAwMTkuNDkuMjZ6bS0yOS4zNCA1LjI0djUuMTJINTYuNjZ2NDYuMjNINDUuMTVWNjkuMjZIMjguODh2LTVhNDkuMTkgNDkuMTkgMCAwMS4xMi01LjE3QzI5LjA4IDU5IDM5IDU5IDUxIDU5aDIxLjgzeiIvPjwvc3ZnPg==","groups":[{"group":"Get started","pages":[{"title":"TypeScript SDK quickstart","href":"/sdks/typescript/quickstart"}]},{"group":"Use the SDK","icon":"code","pages":[{"title":"Use the SDK","href":"/sdks/typescript/use-the-sdk"},{"title":"Troubleshooting","href":"/sdks/typescript/troubleshooting"}]},{"group":"Reference","icon":"file-text","pages":[{"title":"API reference","href":"/sdks/typescript/api-reference"}]}]}]},{"tab":"CLI","icon":"terminal","pages":[{"title":"CLI","href":"/cli/overview"}]},{"tab":"MCP","icon":"plug","pages":[{"title":"MCP","href":"/mcp/overview"}]},{"tab":"Integrations","icon":"puzzle","pages":[{"title":"Integrations","href":"/integrations/overview"}]}]},"basePath":"","title":"Troubleshooting - Sovara","deploymentId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","buildId":"dpl_FZMKUpaaKiVETbfqhoUe4sPFDTmY","dynamics":[],"chunks":[]}