FAQ
Questions are grouped by symptom. If you cannot find an answer, run Route Check on the Monitoring page; it gives the cause for most issues.
Cannot install §
Port is occupied
Default port 3001. Change .env In. PORT That's it. Note that the subscription account will also use three callback ports: 1455, 54545, and 51121, and they are fixed by the upstream and cannot be changed 。
Only one default Compose instance on a host can use local callback authorization at a time. Accounts with existing OAuth JSON can be imported, and Grok can use device authorization.
Changed HOST but it does not take effect inside the container.
Inside the container HOST And DATA_DIR are fixed.
For the Compose main service, BIND_ADDRESS takes precedence for the published host address; HOST is only the fallback. Neither changes the address listened on inside the container.
Start reports permission error
The managed data directory is owner-only. If ownership or link type cannot be verified, the program will refuse to start instead of weakening checks; inspect the owner of DATA_DIR.
Cannot connect §
Client reports connection failure
Use curl first to rule out client configuration issues:
curl --fail http://127.0.0.1:3001/health
A successful check confirms the service; the issue is in client configuration. The common cause is an extra or missing /v1 at the end of the URL; see Client setup.
Prompt is unauthorized / 401
Confirm that you are using AccessKey, not AUTH_KEY or an upstream provider key. Their purposes are different.
Cannot access remotely
The service listens only on 127.0.0.1; this is an intentional security default. Use SSH forwarding or a reverse proxy, do not directly change to 0.0.0.0 to expose to the public network. A leaked management UI exposes every upstream credential; see Security and production.
Model-related §
Prompt indicates the model does not exist
Route inspection is fastest: it identifies whether the problem is the AccessKey, Group, or credential. Use the route-inspection reason codes, change configuration, and run the inspection again.
Want the client to use a different model name
Use Model aliases: the client requests A and the gateway forwards it as upstream model B. Switching providers then requires no code change; see Model management.
Request failed §
Occasional failures recover on retry
This is usually upstream rate limiting. The gateway cools the credential and switches to another; adding more credentials is the most direct mitigation. If it is frequent, check Health for too few available credentials.
A credential was blacklisted
Credentials are blacklisted after the consecutive-failure threshold. API-key Groups are periodically probed and restored after a successful probe; subscription credentials do not use this recovery path and need reauthorization or manual handling. Configure the threshold in runtime settings.
Inference models always time out
These models may reason for a long time before output. Increase First byte timeout, not the request timeout; see Runtime settings for the three timeout types.
Streaming output disconnects midway
Increase Stream idle timeout. If a reverse proxy is in front, ensure it does not buffer streaming responses; Nginx requires proxy_buffering off.
Subscription accounts §
Remote deployment cannot complete OAuth authorization
Because localhost in a browser points to your computer, not the server, the redirect fails. Either paste the full callback URL from the address bar after a redirect failure back into the management UI or use SSH port forwarding; see Subscription accounts.
An account reports that reauthorization is required
Auto refresh failed, usually because the upstream revoked authorization or changed the password. Just go through the authorization process again. For the meaning of the four authorization statuses, see the subscription account page.
Why did the account switch with quota remaining?
Quota information is only for display, not for scheduling decisions. Upstream rate-limit responses trigger switching: the account enters cooldown immediately regardless of its displayed quota.
Usage and cost §
Cost does not match the provider invoice
This is expected. Cost is estimated from upstream token usage multiplied by model prices for operational analysis; it does not equal the bill. Known gaps are missing upstream usage, models without pricing, and non-retroactive price changes.
Cost estimate is clearly too low
Check Data Completeness on the Monitoring page. A high Unpriced cost count means one or more models lack pricing data; a high Missing Usage count means upstream usage is missing. Try Usage Options Injection; see Proxy and request headers.
Operations and maintenance §
Can I run multiple instances?
2.0 is a single-instance deployment and instances do not share state. A load balancer across instances makes scheduling, cooldown, and rate limits independent. For more scale, split into multiple independent deployments by workload.
Can I upgrade from 1.x?
2.0 cannot be upgraded in place, and there is no data import tool. 2.0 is a complete rewrite. Deploy it in parallel, verify it, then switch traffic; see Moving from 1.x.
What must be backed up?
Back up the database together with encryption.key. A database-only backup restores credentials as unreadable ciphertext, and this release does not support changing the master key. See Database and backup.
Logs use too much disk space
Reduce the retention days for request logs (default is 7 days). When request volume is high, this value significantly affects disk usage, especially in deployments using SQLite.
Start with Route checking and Request log in Monitoring and troubleshooting; they reveal most causes. If the issue persists, ask in GitHub Issues with the Request Log error. For security issues, please report privately according to the process in SECURITY.md.