> ## Documentation Index > Fetch the complete documentation index at: https://docs.pylva.com/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Fix common first-run Pylva SDK integration issues, from install and API keys to missing dashboard events. Use this page when the quickstart does not produce a visible event in the dashboard, or when the SDK logs a warning during first setup. ## Fast check Before debugging deeply, verify the first integration path: 1. Install `@pylva/sdk` for TypeScript or `pylva-sdk` for Python. 2. Create an Agent SDK key and store it as `PYLVA_API_KEY`. 3. Call `init` before the provider call you want to track. 4. Wrap one real provider call with a `customer_id` and `step`. 5. Wait for the SDK flush interval, or flush explicitly in a short script. 6. Check the dashboard for the same customer and step. ## Install or import fails | Symptom | Likely cause | Fix | | -------------------------------------- | ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | TypeScript cannot import `@pylva/sdk`. | The package is not installed in the runtime project. | Run `pnpm add @pylva/sdk` in the app or agent package that makes provider calls. | | Python cannot import `pylva`. | The PyPI package name and import name are different. | Install with `pip install pylva-sdk`, then import with `import pylva`. | | LangGraph events do not appear. | LangGraph owns the model call, so provider auto-patching may not see the call. | Use the LangGraph callback path in the SDK docs and pass `metadata.pylva_customer_id`. | ## API key or init problems | Symptom | Likely cause | Fix | | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `InvalidApiKeyError` during `init`. | The key is missing, malformed, or not an Agent SDK key. Data import keys use `pv_cli_*` and fail SDK format validation. | Create an Agent SDK key in Settings -> API keys and store it as `PYLVA_API_KEY`. | | SDK logs `API key was rejected`. | The key was revoked, mistyped, expired, or not valid for the current project. | Create or rotate an Agent SDK key, update the runtime secret, and restart the process. | | `403 WRONG_SCOPE`. | A valid key is being used with the wrong endpoint family. For example, an Admin API key can have a `pv_live_*` prefix but is not an Agent SDK key. | Use an Agent SDK key for SDK telemetry. See [API keys](api/api-keys). | | `SDK not initialized`. | A SDK helper ran before `init`. | Call `init({ apiKey: process.env.PYLVA_API_KEY! })` or `pylva.init(api_key=os.environ["PYLVA_API_KEY"])` during process startup. | ## No events in the dashboard | Symptom | Likely cause | Fix | | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | The provider call succeeds, but the dashboard is empty. | The SDK flushes in the background, about every 5 seconds by default. | Wait a few seconds and refresh the dashboard. In short scripts, call `flush` before exit. | | A local script exits immediately after one call. | The process may exit before the buffered event is sent. | In TypeScript, call `await flush()`. In Python sync scripts, call `asyncio.run(pylva.flush())`. | | Events appear without the expected customer or step. | The provider call was not inside a tracking context, or the LangGraph callback metadata did not include a customer id. | Wrap the call with `track` or `track_context`, or pass `metadata.pylva_customer_id` in LangGraph. | | Events never appear from a provider path. | The provider or framework path may not be auto-instrumented. | Check [Supported Integrations](concepts/supported-integrations), use the callback path for LangGraph/LangChain, or report usage explicitly for unsupported paths. | | Events go to the wrong deployment. | A self-hosted runtime is using the cloud endpoint, or a cloud runtime has a stale `endpoint` override. | Omit `endpoint` for Pylva Cloud. For self-hosted deployments, pass the deployment origin consistently. | ## Flush a short script TypeScript: ```ts theme={null} import { flush } from "@pylva/sdk"; await flush(); ``` Python: ```python theme={null} import asyncio import pylva asyncio.run(pylva.flush()) ``` ## API responses and warnings | Symptom | Likely cause | Fix | | ----------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | `401 INVALID_API_KEY`. | The key is missing, invalid, revoked, or expired. | Create a new Agent SDK key and update the runtime secret. | | `403 WRONG_SCOPE`. | The key is valid, but not allowed for the endpoint. | Use an Agent SDK key for SDK telemetry, rules, pricing, and budget sync. | | `429 RATE_LIMIT_EXCEEDED`. | The key exceeded the per-key request limit. | Reduce flush frequency, batch events through the SDK, and retry after the `Retry-After` header. | | `400 VALIDATION_ERROR`. | A direct API request does not match the wire schema. | Prefer the SDK. If calling the API directly, use the full event shape from [Submit telemetry events](api/events). | | `pricing not yet configured`. | Pylva accepted usage, but does not yet have pricing for that provider/model or metric. | Add the missing pricing in the dashboard before relying on margin or billing reports. | ## Missing cost sources For the full coverage workflow, see [Cost Source Discovery](concepts/cost-source-discovery). | Symptom | Likely cause | Fix | | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | A vendor bill is higher than Pylva usage. | A non-LLM source may not be reported, or a provider path may not be auto-instrumented. | Inventory the paid source, add `reportUsage` or `report_usage`, and run `pylva validate` to check for unapproved sources. | | `pylva validate --ci` fails. | The repository contains a newly detected source that is not approved in `.pylva/approved-sources.json`. | Run `pylva validate --approve` locally, declare the source with a Data import key, and commit the updated approval file. | | Spend unexpectedly drops to zero for one source. | Instrumentation may have been removed, renamed, or deployed without the right runtime path. | Check recent code changes, metric names, and source health alerts before treating the cost drop as real savings. | ## Budget hard stops For safe rollout guidance, see [Controls Workflow](concepts/controls-workflow). | Symptom | Likely cause | Fix | | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `PylvaBudgetExceeded` is thrown. | An active hard-stop budget rule was cached by the SDK and blocked the next provider call before spend increased. | Catch `PylvaBudgetExceeded` and return a product-specific fallback such as a cached answer, smaller model path, queued job, or human handoff. | | Calls are not blocked while Pylva is unreachable. | Pylva is designed to fail open when pricing, rules, or backend state is unavailable. | Check rule activation and SDK cache timing. Hard stops block only when the SDK has the active rule state needed to enforce safely. | ## Webhook alerts For the full delivery workflow, see [Alert Delivery And Webhooks](concepts/alert-delivery-and-webhooks). | Symptom | Likely cause | Fix | | ------------------------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- | | An expected alert did not arrive. | The rule has no enabled alert channel, the webhook config is disabled, or delivery failed after retries. | Check the rule's alert channels, webhook enabled state, and the dead-letter queue. | | Webhook signature verification fails. | The receiver is verifying a parsed body, stale secret, wrong timestamp header, or malformed signature. | Verify the raw request body with `X-Pylva-Signature`, `X-Pylva-Timestamp`, and the saved signing secret. | | A DLQ entry appears. | Pylva could not deliver the alert after retries, or the webhook config was deleted before dispatch. | Fix the receiver or channel configuration, then retry the DLQ entry. Dismiss it only when no follow-up is needed. | ## Privacy mistakes Do not send prompts, completions, raw messages, emails, phone numbers, API keys, authorization headers, request bodies, or raw tool arguments in telemetry metadata. Pylva needs cost-shaped usage facts: customer id, step name, provider, model, token counts, status, latency, metric, and metric value. See [Privacy and PII](concepts/privacy-and-pii) for the full data boundary.