LinuxAir
Docs / FAQ & troubleshooting

FAQ & troubleshooting

Answers to the questions we hear most, grouped by topic.

Routing

It keeps choosing the same model. Why?
Usually because fingerprints are too similar to separate models — common with the offline embedder and no judge. Configure an embedding model and a judge, rebuild clusters and re-probe. Also check that your tolerance isn't so small that only the top model qualifies (Best quality mode), and that prices are correct.
It always picks the cheapest model.
Check the mode: Economy or a large custom tolerance allows bigger trade-downs. Also confirm the stronger models are Active and not excluded by a max_cost or allow-list.
Can I force a specific model?
Yes — send its id as model. The request is still logged, metered and eligible for failover.
Does it work with tools / function calling and JSON mode?
Yes. tools, tool_choice and response_format are passed through. Answer checks are skipped for tool calls.
What happens on very long prompts?
Models whose context window can't fit the prompt plus a reasonable answer are excluded before scoring. If none fit, you get no_eligible_model.

Models & pricing

A model shows "No price found".
The feed had no match for that id. Edit the model and enter prices manually; they will be locked against automatic updates.
Fingerprinting failed.
Every probe call errored. The most common causes are a wrong model id, a key without access to that model, or a rate limit. Test the provider, fix the issue and click Re-probe.
Why is the Groq/Together price marked Estimated?
It was matched to a similar listing from another host. Hosts set their own prices, so confirm it against the provider's page.

Cache, caps & privacy

Why did a request come back instantly and free?
It was served from the semantic cache — a near-identical prompt with the same model settings was answered recently. The response carries cached: true and the X-LinuxAir-Cache header. Send la: {"cache": false} to bypass it, or lower the TTL in Routing policy.
I got 402 budget_exceeded.
A daily or monthly spend cap was reached, or a per-key cap. Raise it in Routing policy (or on the API key), or wait for the period to roll over. Nothing was charged for that request.
Redaction is masking too much.
Turn off the categories you do not need under Routing policy — for example leave phone numbers alone if your prompts are about call routing. Custom patterns are regular expressions, one per line.
The model I need is being skipped for tool calls.
Its capability check failed. Re-probe it, or override Supports tool calling in the model edit dialog if you know the check was wrong.

Teams

An invite says the email already owns a workspace.
That address created its own workspace, so it cannot join another. Use a different address, or have them delete their workspace first.
A developer cannot change billing or policy.
That is by design. Only Owners can change billing, spend caps, routing policy and members.
The invite email did not arrive.
Copy the invite link from the members table and send it directly. Check your mail settings if this keeps happening.

Billing

I got 402 insufficient_credits.
Your credit balance can't cover the routing fee. Top up under Billing; nothing was charged for the failed request.
Are failed requests charged?
No. Only successful routed requests use credits.
My payment succeeded but credits didn't appear.
Refresh the Billing page — Stripe payments are confirmed on return and by webhook. If it still doesn't show, contact support with the payment reference; each payment is credited exactly once.

Self-hosting

Permission errors in the server logs after install.
Usually a command was run as root earlier, leaving root-owned files. Fix ownership of the application and log directories for the service user, then restart the services.
The API returns 503 not_ready.
The routing space hasn't been built. Open Platform → Router and click Rebuild clusters, and make sure the long-queue worker is running.
Models stay in "Probing" forever.
Background workers aren't running. Start the worker processes for the default and long queues; the hourly job then recovers interrupted probes.
Streaming arrives all at once.
Your reverse proxy is buffering. Add proxy_buffering off for /v1/ and raise the application server timeout.
Still stuck? Contact us with the request id (from the linuxair block or the Requests page) and what you expected to happen.