Troubleshooting

Use this page when SDK activity is missing, subjects are not attached, SDK leads are not created, or lifecycle outcomes are not visible.

No SDK activity appears

Check these first:

• track(server, vendorSlug, options) is called on the MCP server instance used by the running process.
• options.apiKey or WITHIN_SDK_API_KEY is present in the MCP server runtime.
• If you use the legacy key environment variable, WITHIN_SDK_INGEST_KEY is present in the MCP server runtime.
• vendorSlug matches the slug in your Within vendor settings.
• The MCP server uses a supported @modelcontextprotocol/sdk server shape.
• A custom apiBaseUrl is a Within API origin, not a complete /v1/ingest/* endpoint.

If the adapter is unsupported, the SDK returns your server unchanged and logs a diagnostic line when possible.

Startup is visible, but calls are not

The SDK can only observe tool calls that pass through the tracked server instance.

Verify that:

• tools are registered on the same server instance that is passed to track()
• the running process imports the tracked server, not a separate server instance
• the process stays alive long enough for background reporting
• your test is calling a real tool, not only initialize or tools/list

Subject is missing

Subject context comes from options.identify.

If identify() is missing, throws, returns null, or returns an empty userId, that request remains anonymous without falling back to an earlier request. Otherwise the SDK hashes userId locally into a subject, drops userName, and sends redacted userData.

SDK lead is not created

An SDK lead requires a subject and enough meaningful activity to reach the scoring threshold.

Common reasons:

• only anonymous activity was captured
• the workflow only called ping, health, status, catalog, or get_more_tools
• tool calls failed and did not earn successful-result points
• the scoring threshold was configured above the default

Conversion is not visible

Check that reportConversion() runs in trusted server-side code with the same opaque vendor-local userId used by identify(). The SDK creates the subject locally, so different IDs produce different subjects. Also verify that the vendor slug and SDK API key belong to the same vendor.

Repeated reports for the same subject and UTC date are idempotent and return inserted: false.

Salesforce CRM outcome is rejected

After the upcoming connector release, the Salesforce connector must use the vendor's SDK API key and exact vendor slug. Each batch must contain 1–100 outcomes. Each outcome requires a 64-character hexadecimal idempotency_key and subject, a supported outcome_type, a valid occurred_at timestamp, and a valid source_mapping.

Individual invalid outcomes return status: "rejected" in an otherwise successful batch. Missing or invalid credentials reject the entire request. Raw Salesforce record IDs, user IDs, names, email addresses, and phone numbers are not accepted.

Within reporting affects tool calls

It should not. Reporting is asynchronous. The original tool result is returned and original tool errors are rethrown regardless of Within availability.

Local verification

In local development, the SDK writes setup and reporting diagnostics to ~/within-sdk.log when file logging is available (in Python, when debug mode is enabled). In edge runtimes where local file logging is unavailable, it falls back to console logging.

To replace the local destination, provide options.log. These operational messages are separate from persisted SDK activity: initialization and tools-list events continue to appear in SDK Activity and Session Replay.

track(server, 'acme', {
  apiKey: process.env.WITHIN_SDK_API_KEY!,
});