The connection check fails
Confirm the key belongs to the selected project and is active. Use Read and write for telemetry, receipts or evaluation APIs. Keep service keys server-side; never use a management token. Both SDKs default tohttps://app.hue.run. Overrides must be origins, without /api or OTLP paths. Hosted origins require HTTPS; loopback HTTP works locally, and TypeScript requires allowInsecureHttp: true for other HTTP hosts.
Report the error and project without the key or authorization header. TypeScript HueConnectionError includes HTTP status or a network, timeout or parsing cause.
No trace appears
- Verify the key with
checkConnection()(TypeScript) orvalidate_project()(Python). - Confirm instrumentation: direct provider calls emit no telemetry without an integration or manual span.
- Await flush before exit; inspect the same project. Session IDs group requests, not projects.
- Check exporter failures, rejected records and queue limits.
A parent span is missing
Children may arrive before parents. Flush participating providers and allow ingestion to finish. A parent may be sampled out, excluded or sent elsewhere; preserve its original ID when diagnosing. An OpenTelemetry status ofUnset means no explicit status was recorded. It is not itself an application failure.
A trace stays running
Hue shows Running while a Hue or AI span remains open (usually after 1.5 s), then resolves it when finished spans arrive. After 15 minutes without a span, log or end, it shows No end received. Await flush before exit; processors forwarding starts must also forward ends. Later telemetry makes it Running again.Input or output is missing
Check the content setting first:captureContent: false or capture_content=False omits content on purpose, including recognized content attributes from other instrumentation on the same provider. Data privacy explains both modes.
Content must also be supplied by the instrumentation. The SDK does not reconstruct prompts, invent an output or estimate missing usage, and an absent output is different from JSON null. Make sure the request span records the user’s input and the reply; see Traces and spans. Helper spans never record exception messages or stack traces, only error.type and the span status.
An app HTTP response is missing
CheckcaptureHttp / capture_http, captureHttpBodies / capture_http_bodies and the overall content setting. Default HTTP capture requires TypeScript 0.26.0 or Python 0.14.0. Initialize Hue before API clients, and check whether the request used a supported client in the same process. A remote tool or subprocess needs its own instrumentation.
Identity-only spans, binary content, unread streams and truncated bodies do not prove a complete app exchange. A tool’s summary is still the tool’s result; changing that summary does not recover the API response. Inspect the HTTP child spans and the build’s missing or incomplete evidence. See app HTTP exchanges.
Streaming spans end too early
Keep the request span open while the stream is consumed, including tool execution and the final output. Awaiting only the initial stream object does not mean generation has finished. The TypeScript SDK handles Hue delivery automatically in Vercel Functions; see Vercel Functions and Workflow. With Python or other serverless hosts, await the telemetry flush in the framework’s supported after-response lifecycle. Do not shut down a shared provider after every request. Shut it down when the application stops.Flush reports a failure
TypeScriptflush() throws HueExportError for rejected or failed export work. Python force_flush() returns False for an observed export failure, dropped record, instrumentation omission or timeout. Use the bounded safe variants in serving application lifecycles; see TypeScript production setup and Python production setup. Inspect their sanitized status reports; do not discard those results.
In-memory queues can lose records on termination, overflow or sampling. A timeout does not prove rejection. Hue deduplicates exact completed-span or log replays, but rerunning work or changing IDs creates records; inspect partial-batch rejections before retrying.
OTLP requests are bounded. The SDK splits batches; values may be cut when uploads or request budgets are exhausted.
Large values or files are cut off or show Not uploaded
Over-limit string attributes and recorded media upload apart from the span, after it is exported. A file whose upload has not finished, or failed, shows Not uploaded until the same bytes are uploaded under the trace. Flush or shut down with a budget that covers your uploads, allow HTTPSPUT to Hue’s upload URLs if your egress policy restricts it, and check uploadFallbacks in hue.transport.getReport() or upload_fallbacks in hue.export_status. Media explains what falls back and why.
The example throws Cannot use import statement outside a module
Node.js treats .js and .ts files as CommonJS unless the nearest package.json contains "type": "module". Run npm pkg set type=module in the example directory, or name the file first-trace.mjs / trace.mts, then run it again. A CommonJS application on Node.js 22.12 or later can instead load the package with require("@hue-run/sdk").
Installation reports a dependency conflict
See the compatibility matrix. SDK core supports AI SDK 6 viahueExperimentalTelemetry(hue); hueTelemetry requires AI SDK 7. Python accepts OpenTelemetry >=1.40,<2 (1.45.1 certified; 1.40.0 tested floor). Keep existing instrumentation and use a standard OTLP exporter outside the matrix; do not force incompatible installs.
A JSON Schema evaluator reports SchemaValidatorUnavailable
The validator is optional in both SDKs. Run npm install ajv (8.17 or later) for builtins.jsonSchema in TypeScript, or pip install 'hue-run[evals]' for builtin_scorers.json_schema in Python; without it the Python helper raises ImportError. Other built-in evaluators do not need these packages.
Listing eval-set cases fails for a large page
Evaluation clients cap responses at 4 MiB. A valid page of full cases can exceed that cap when inputs or references are large. Request a smaller explicit page limit and follownextCursor, for example client.listCases(versionId, { limit: 10 }) or client.list_cases(version_id, limit=10). The local runner reads summaries and individual cases and does not use this full-case page path.
A response-size or connection failure does not prove that a mutation was rejected. Preserve its idempotency key and inspect the outcome before retrying application work.
The trace is present but the evaluation fails
Check which outcome failed: the original application execution, the evaluator’s execution, or the quality assessment. A booleanfalse is a valid scored result. Historical rescoring assesses frozen evidence and does not rerun your application.
The MCP server rejects the agent
The MCP server accepts a Read or Read and write project key, or a Hue sign-in connection. For authentication, connection and tool-list issues, see MCP troubleshooting; for trace fields, limits and errors, see MCP tools.Tracing is disabled or data is being dropped
CheckHUE_TRACING_ENABLED, package versions, initialization failures and pending bytes and records. Safe initialization can disable tracing while application work succeeds. 429 means the minute allocation was exhausted; 503 can mean saturation, timeout or unavailable persistence. Respect Retry-After; do not repeat business work. See Requests are rate limited.
Requests are rate limited
Each project allows 600 telemetry requests, 20,000 new records and 32 MiB logical payload per one-minute window; spans and logs share it. Managed-evaluation root spans use a separate path, so upload limits cannot block orchestration evidence. That path retains tenant checks, deadlines, trace limits and deduplication; uploads cannot select it. The window starts on admission; the next reservation or final evidence charge after 60 seconds starts another. Requests count at admission; records and payload count at storage. Authenticated attempts, including failed writes or retries, use request allowance; exact retries do not add records or payload. Admission limits return 429 or 503 withRetry-After; client queues can still overflow.
Tracing uses a bounded database pool separate from application queries. Page-triggered naming uses that pool for at most 30 traces per visit, one at a time; failures leave traces unnamed for a later visit.
These are protective limits, not an SLA. Ask Hue to size the allowance for your instances, request rate, spans and payload; measure latency and overhead under expected concurrency. Local benchmarks do not establish production capacity.
For longer outage buffering, consider a separately operated OpenTelemetry Collector with explicit memory, queue and storage limits. Durable queues add disk and retention failure modes and do not remove instrumentation overhead. See Collector resilience guidance.