Troubleshooting

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:

Install @pylva/sdk for TypeScript or pylva-sdk for Python.
Create an API key and store it as PYLVA_API_KEY.
Call init at process startup - provider calls made before init runs are not recorded.
Wrap one real provider call with a customer_id and step.
Wait for the SDK flush interval, or flush explicitly in a short script.
Check the dashboard for the same customer and step; events appear within a few seconds of a flush.

See SDK diagnostics

There is no verbosity flag today; both SDKs surface problems through their normal logging:

TypeScript prints [pylva]-prefixed console warnings and errors: per-rejected-event warnings, pricing warnings once per provider+model, a buffer-overflow warning, and a loud error (with batch drop) on the first 401.
Python logs through the standard library logger named pylva at warning level. Enable it with logging.basicConfig(level=logging.WARNING) or attach a handler to logging.getLogger("pylva").

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 or malformed. Any Pylva key works, including legacy `pv_cli_*` keys.	Create an API 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 a new API key, update the runtime secret, and restart the process.
`403 WRONG_SCOPE`.	Only returned by Pylva releases older than the universal key, where key types gated endpoint families.	Upgrade the deployment, or on legacy releases use a key of the matching type. See 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, 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.
No events and `[pylva]` logs show network errors.	The runtime cannot reach the ingest endpoint (proxy, TLS interception, egress rules). The SDK fails open: it buffers, retries, then drops - your app keeps working.	Allow egress to `api.pylva.com:443` (or your self-host origin) and check the SDK logs described above.
Events missing from serverless runtimes (Lambda, Vercel Functions).	The runtime can freeze or exit before the background flush fires.	Call `flush` at the end of each invocation before returning.

Flush a short script

TypeScript:

import { flush } from "@pylva/sdk";

await flush();

Python:

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 API key and update the runtime secret.
`403 WRONG_SCOPE`.	Legacy releases only — current releases accept any valid key on every machine endpoint.	Upgrade the deployment, or on legacy releases use a key of the matching type.
`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.
`403 TIER_LIMIT_REACHED`.	The workspace hit its monthly event cap. Telemetry is rejected but your application keeps working; the `X-Pylva-Tier-Usage` header shows `current/limit`.	Upgrade the plan or wait for the window to reset. See Plans and limits.
`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.

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 with `PYLVA_API_KEY` set, declare the source, 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.

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.

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 for the full data boundary.

Get started

SDKs

Concepts

API reference

Troubleshooting

Fast check

See SDK diagnostics

Install or import fails

API key or init problems

No events in the dashboard

Flush a short script

API responses and warnings

Missing cost sources

Budget hard stops

Webhook alerts

Privacy mistakes

​Fast check

​See SDK diagnostics

​Install or import fails

​API key or init problems

​No events in the dashboard

​Flush a short script

​API responses and warnings

​Missing cost sources

​Budget hard stops

​Webhook alerts

​Privacy mistakes

Fast check

See SDK diagnostics

Install or import fails

API key or init problems

No events in the dashboard

Flush a short script

API responses and warnings

Missing cost sources

Budget hard stops

Webhook alerts

Privacy mistakes