Troubleshooting Trace Issues in Typescript Vercel AI-SDK for Phoenix

If your span filter is logging but traces are not appearing in Phoenix Cloud, the most common issues are: (1) incorrect API key or endpoint, (2) missing required Phoenix resource attributes, or (3) network/exporter errors. Your code and environment variable setup generally match the official Phoenix Vercel AI SDK tracing guide and TypeScript tracing quickstart, but there are a few things to check: 1. API Key and Endpoint: Ensure PHOENIX_API_KEY is set to your actual Phoenix Cloud API key (not an empty string), and PHOENIX_COLLECTOR_ENDPOINT should be https://app.phoenix.arize.com/v1/traces (no angle brackets). 2. Resource Attributes: You should set the Phoenix project name using the attributes option in registerOTel, e.g., attributes: { [SEMRESATTRS_PROJECT_NAME]: SERVICE_NAME }. 3. Exporter Errors: If spans are being created but not exported, check for errors in the browser/server logs related to the OTLP exporter. 4. Telemetry Enablement: Ensure you are calling your LLM with experimental_telemetry: { isEnabled: true } (not just enabled: true). 5. BatchSpanProcessor Flushing: The BatchSpanProcessor may not flush before the process exits—try using the SimpleSpanProcessor for debugging, or ensure your app stays alive long enough for the batch to export.Example minimal working setup (from the official docs): LBKSimport { registerOTel } from "@vercel/otel"; import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-proto"; import { isOpenInferenceSpan, OpenInferenceSimpleSpanProcessor } from "@arizeai/openinference-vercel"; import { SEMRESATTRS_PROJECT_NAME } from "@arizeai/openinference-semantic-conventions";LBKSexport function register() { registerOTel({ serviceName: "phoenix-next-app", attributes: { [SEMRESATTRS_PROJECT_NAME]: "your-next-app", }, spanProcessors: [ new OpenInferenceSimpleSpanProcessor({ exporter: new OTLPTraceExporter({ headers: { api_key: process.env["PHOENIX_API_KEY"] }, url: process.env["PHOENIX_COLLECTOR_ENDPOINT"] || "https://app.phoenix.arize.com/v1/traces", }), spanFilter: isOpenInferenceSpan, }), ], }); }LBKSIf you still see logs in the span filter but no traces in Phoenix, double-check the API key, endpoint, and look for exporter errors. Would you like a step-by-step troubleshooting checklist?Sources: - Vercel AI SDK Tracing (JS) | Phoenix - TypeScript tracing quickstart

The OTLPExporterError: Unauthorized with code 401 means your Phoenix Cloud API key is missing or incorrect. You must set PHOENIX_API_KEY to a valid API key from your Phoenix Cloud account—an empty string or placeholder will not work. Also, ensure your PHOENIX_COLLECTOR_ENDPOINT is set to https://app.phoenix.arize.com/v1/traces without angle brackets. The duplicate "trace" registration warning is usually harmless but can occur if the OpenTelemetry provider is registered more than once; ensure your instrumentation setup runs only once per process. Would you like detailed steps to resolve the API key issue?Sources: - Vercel AI SDK Tracing (JS) | Phoenix - TypeScript tracing quickstart - Authentication | Phoenix

If you are still seeing OTLPExporterError: Unauthorized (401) even with the correct system API key and collector URL, double-check that the API key is being sent in the correct header. For Phoenix Cloud, the header should be api_key, not Authorization. Your OTLP exporter config should look like: LBKSexporter: new OTLPTraceExporter({ headers: { api_key: process.env["PHOENIX_API_KEY"] }, url: "https://app.phoenix.arize.com/v1/traces", }),LBKSAlso, ensure there are no extra spaces or invisible characters in your API key or endpoint. If the error persists, try restarting your app and verify that the environment variable is available at runtime (not just at build time).Would you like a checklist to debug environment variable loading and header formatting?Sources: - Vercel AI SDK Tracing (JS) | Phoenix - TypeScript tracing quickstart

If you are still getting a 401 Unauthorized error despite using the correct API key and endpoint, the most likely causes are: 1. The API key is not being injected into the runtime environment where the OTLP exporter runs (e.g., Vercel serverless functions may require secrets to be set in the Vercel dashboard, not just .env files). 2. The API key or endpoint has invisible characters or whitespace—try logging their values with delimiters to confirm. 3. The OTLP exporter is not picking up the environment variable at runtime (e.g., due to build-time vs. runtime variable resolution).This exact setup is supported and should work if the API key is present in the api_key header and the endpoint is correct, as shown in the official Phoenix docs. Would you like step-by-step instructions to debug environment variable injection in your deployment environment?Sources: - Vercel AI SDK Tracing (JS) | Phoenix

If you have confirmed via console log that process.env.PHOENIX_API_KEY is correct immediately before OTLPTraceExporter is constructed, but you still get a 401 error, the issue is almost certainly with how the header is being sent or interpreted by Phoenix Cloud.Checklist: 1. No Angle Brackets: Ensure your endpoint is exactly https://app.phoenix.arize.com/v1/traces (no < > ). 2. No Extra Spaces: Log the header as { api_key: process.env["PHOENIX_API_KEY"] } right before passing to the exporter, and check for whitespace or invisible characters. 3. Vercel Environment: If deploying on Vercel, ensure the secret is set in the Vercel dashboard and not just in .env (Vercel does not load .env for serverless by default). 4. No Build-Time Substitution: Make sure the value is available at runtime, not just at build time. 5. No Multiple Exporters: Only one exporter should be sending to Phoenix; multiple registrations can cause issues.If all of the above are correct and you still get 401, try regenerating the API key in Phoenix Cloud and updating your secret.Would you like a minimal working example or more troubleshooting steps?Sources: - Vercel AI SDK Tracing (JS) | Phoenix - TypeScript tracing quickstart

Yes, there are relevant Slack threads discussing similar issues with TypeScript-based instrumentation and Phoenix. Here are the most pertinent ones: 1. Slack thread: TypeScript telemetry setup and troubleshooting – This thread covers issues with setting up telemetry in TypeScript, including package versions and deprecation warnings. 2. Slack thread: Duplicate registration and environment variable issues – This thread discusses problems with TypeScript/Node.js instrumentation, including errors related to object extensibility and registration order.Would you like a summary of the key insights from these threads?Sources: - TypeScript telemetry setup and troubleshooting - Duplicate registration and environment variable issues