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
The default port is 3001. Change PORT in .env to use another port. Subscription accounts also use callback ports 1455, 54545, and 51121, which are 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.
HOST and DATA_DIR are fixed inside the container.
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
Try Refresh credentials from the account card's More menu; reconnect or import the account if it still fails. The same applies to Outcome unknown. Refresh quota does not restore authorization. See Subscription Accounts for the four authorization states.
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. Costs are estimated from upstream token usage, model prices, and the group and access-key price multipliers for operational analysis; they are not invoices. Known differences include requests without upstream usage, models without prices, and price changes that do not recalculate historical costs.
Cost estimate is clearly too low
Check Data Completeness on the Monitoring page. A high Unpriced count means some models need prices; add them. A high Missing Usage count means you should check whether the upstream returns usage data; see Monitoring and Troubleshooting.
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.