Troubleshooting and FAQ

Nothing appears in burn today

Start with the live view while you make a request:

burn watch

If nothing appears there either, check these in order:

1. The request went through the proxy. The base URL must point at 127.0.0.1:8787 and include the right route, such as /openai/v1 or /anthropic. A request sent directly to the provider is invisible to burn.
2. The proxy is running. If it is not, the SDK connection fails. If another process is on the port, the SDK may be talking to something else.
3. The response actually reported usage. burn logs only requests where the provider returned usage. Errors, blocked calls, and cancelled streams are not logged.
4. The response shape is known. burn parses OpenAI chat completions, the OpenAI responses API, and Anthropic messages, for both JSON and SSE. A provider that reports usage in a different shape is forwarded normally but not logged.
5. The ledger is the one you think it is. BURN_HOME must be the same for the proxy and the report. Check the file path with burn reset only if you intend to delete rows, or inspect ~/.burn directly.

burn run prints a hint when its child process made no requests at all. That usually means the SDK did not pick up the base URL.

A request has no price

The model was not in the price book when the request finished. burn stores the row with no cost and does not guess.

burn price update
burn price recalc

If the model is still unpriced, set a price by hand:

burn price set my-model 0.5 1.5
burn price recalc

The numbers are USD per 1 million tokens: input then output. See Pricing for the matching rules and cache multipliers.

The port is already in use

The default proxy port is 8787 and the default UI port is 4747. Pick another one:

burn proxy --port 8788
burn ui --port 4748

If you move the proxy port, update the base URLs in your app. burn env --port 8788 prints the right lines. A port value in config.json changes the default for burn proxy and burn env, but not for burn ui.

The proxy returns 429

A blocking budget is in effect and today's spend has reached the limit. Check it:

burn budget

Raise it, remove it, or keep the limit and stop blocking:

burn budget daily 10
burn budget daily 10 --block
burn budget off

The 429 comes from burn, not the provider. The response body includes spent and budget.

Anthropic requests 404

The Anthropic SDK appends /v1/messages itself. Set the base URL to the route without /v1:

http://127.0.0.1:8787/anthropic

If you use http://127.0.0.1:8787/anthropic/v1, the request becomes /anthropic/v1/v1/messages.

Prices will not update

Check the price status first:

burn price

It prints the source, the last fetch time, the number of models, whether the bundled fallback is in use, and whether offline mode is on.

• If BURN_OFFLINE is set, price fetching is disabled by design. Unset it for the process that runs the update.
• If the download fails, the cached copy stays in use. burn price update reports the error. Check network access to the source, or set BURN_PRICE_URL to a mirror.
• A stale cache is not a failure. The proxy refreshes in the background when the cached copy is more than 24 hours old, and keeps serving requests while it does.

Frequently asked questions

Does burn store prompts or responses?

No. The database has no prompt or response column. burn reads usage from the response as it passes through and writes metadata only. The project page lists every stored field.

Does burn send telemetry?

No. There are no analytics, no accounts, no identifiers, and no usage uploads. The only network call burn makes itself is the price list download. Set BURN_OFFLINE=1 to turn even that off.

Does it work with streaming?

Yes. burn reads usage from server-sent events and forwards the stream as it arrives. For OpenAI chat completions with stream: true, it adds stream_options.include_usage when the caller did not ask for it, so the final chunk includes usage. If a provider's stream does not report usage, the request is not logged.

Can I use several providers at once?

Yes. One proxy serves every route. Point each SDK at its own route, and the rows are stored with the provider name. burn by-provider groups them.

Can I tag requests from different projects?

Yes. Send x-burn-tag: <tag> on the request. burn stores up to 200 characters and strips the header before forwarding. Then use burn by-tag.

Why is the dashboard total different from burn today?

burn today starts at local midnight. The dashboard's 24h tab is a rolling window: the last 23 hours floored to the hour, through now. Use the 24h, 7d, 30d, or 90d tabs for rolling windows, and the summary commands for local calendar ranges.

Can I export the data?

Yes. burn export writes CSV, and burn export --json writes JSON. Both include every logged row, not just the current range.

How do I delete everything?

burn reset --yes deletes every logged request. It leaves the config and the cached prices. To remove everything, delete the BURN_HOME directory, which is ~/.burn by default.

Does it work on Windows?

Yes. burn requires Node 22.5 or newer. burn run uses the platform shell on Windows, and the rest of the commands behave the same.

Is there a hosted version?

No. burn is a local tool. There is no cloud account and no server component.

How do I report a bug or request a feature?

Open an issue on GitHub. The changelog is here.