Gateway troubleshooting
Most gateway issues come down to the upstream URL, the profile, or the port. Start with neuraframe status and neuraframe logs.
Requests return a 502 saying the provider is unreachable
This is honest failure working as intended: the request was not in memory and the Gateway could not reach your provider. Check that gateway.upstream_url is correct and reachable from the host, that outbound network and any firewall allow it, and that your provider is up. Anything already learned still serves from memory.
neuraframe config get gateway
curl -sS https://api.your-provider.com -o /dev/null -w "%{http_code}\n"
Everything is forwarded and nothing is reused
Two common causes. First, the license may be missing or expired, in which case the Gateway is in transparent pass-through by design; run neuraframe status. Second, the profile may not match your provider, so the meaning layer is off; set gateway.profile to your provider or auto and restart. The exact layer still reuses identical repeats regardless of profile.
My provider rejects the request (401 or 403)
The Gateway forwards your API key untouched, so an auth error almost always means the key or auth header did not travel from your app. Confirm your app still sends its usual header (Authorization: Bearer for OpenAI and xAI, x-api-key plus anthropic-version for Anthropic). NeuraFrame™ does not add, store, or require a provider key of its own.
Port already in use
Another process is on the gateway's listen port. Change it and restart.
neuraframe config set gateway.listen 127.0.0.1:8082 sudo systemctl restart neuraframe-studio
Streaming looks different through the gateway
It should not: a miss forwards the request unchanged and returns the response unchanged, byte identical, including streamed tokens. If a streamed response differs, you are likely pointing at a different upstream path than before. Confirm the base URL and path in the provider table.
Paraphrase (semantic) reuse shows zero
The meaning layer needs an embedding endpoint to operate (embedding_url in the config). If it is missing, unreachable, or misconfigured, exact reuse still works but paraphrases are never recognised. The gateway tells you: check the service log for a semantic warning at startup, and curl http://127.0.0.1:8081/_nf/savings, whose semantic block reports the endpoint and whether it answered. If you only front a hosted provider, note that providers such as Anthropic do not expose an embeddings API, so there is no local endpoint until you run one: any local embedding server works (for example llama.cpp with --embedding), pointed to by embedding_url (default http://127.0.0.1:8080/embedding). Restart after changing it and the startup check will confirm.
A reworded question went to the model even though a similar one was answered before
By design. Before serving a remembered answer for a reworded question, the gateway requires the new question to genuinely be a rewording of one the answer was given for. A question that swaps a key term (the capital of France versus the capital of Germany) looks similar but needs a different answer, so it goes to the model rather than the memory. This deliberately gives up some reuse to guarantee a look-alike question can never be served the wrong answer. Novel and swapped-term questions costing a model call is the system working, not failing.
Reuse rate is lower than expected with freshness on
Freshness re-fetches time-sensitive answers once their window passes, so some repeats are deliberate model calls. See what it is doing at curl http://127.0.0.1:8081/_nf/freshness: volatile_marked counts answers given a window, and the report lists any learned or verified-stable classes. A mis-flagged stable question corrects itself after a couple of verified-unchanged re-fetches. If your workload is entirely stable content, you can pin paths stable (neuraframe freshness stable_paths <p1,p2>), turn detection off (neuraframe freshness detect off), or clear what it has learned (neuraframe freshness forget). Comparing with freshness fully off (neuraframe freshness off) isolates its effect.
A setting I changed is not taking effect
CLI and config changes are read when the service starts: run sudo systemctl restart neuraframe-studio after a change. The live counters at /_nf describe the running process, so they reflect the change only after that restart.
Still stuck
Collect neuraframe doctor output and recent neuraframe logs. If you have an account, open a request in the help desk inside your account (the Support tab), where we can see your licenses and devices and track it with you. You can also reach us from the contact page.