2.0 known limitations and versioning
Review 2.0 runtime boundaries, compatibility, and release channels in one place before deploying, upgrading, or switching production traffic.
Deployment and data §
2.0 guarantees correctness only for one application instance. Scheduling, cooldown, rate-limit, and affinity state is not shared across instances; an external database does not add horizontal scaling.
To isolate workloads or add capacity, split them into independent deployments by business boundary instead of placing more instances behind a load balancer for the same configuration.
Review security and production guidance →
2.0 cannot open, import, or convert 1.x data. The two versions must use separate databases, data directories, ports, and Docker volumes.
Deploy 2.0 in parallel, reconfigure and verify it, then switch traffic. Keep the original 1.x instance until the rollback window closes.
Schema migrations required by version upgrades run automatically at startup. When switching among SQLite, MySQL, and PostgreSQL, GPT-Load does not copy existing configuration or data.
When changing drivers, use a new database, reconfigure and verify it, then switch traffic. Do not confuse this with automatic schema migration.
Review database and backup guidance →
Cost and soft limits §
Cost is calculated from token usage returned by upstream and model prices. Requests missing usage or pricing cannot be fully priced, and price changes do not recalculate history.
These figures are suitable for operational analysis and incident protection, not financial reconciliation.
The gateway charges estimated cost to the limit only after a request completes. One large request or concurrent requests already admitted can exceed the threshold; unpriced requests or requests without usage are not counted.
For a strict budget, also use provider billing alerts, budgets, or hard quotas.
Review AccessKey cost limits →
Stateful Responses resources §
previous_response_id, conversation, and other resource IDs usually depend on the upstream credential that created them. Current affinity does not read these IDs and cannot guarantee that a later request returns to the original credential.
For reliable stateful resources, keep one credential in the Group or confirm that upstream allows resources to be shared across credentials.
Review protocol and conversion boundaries →
Encryption key §
If ENCRYPTION_KEY is replaced or lost, existing channel credentials cannot be decrypted. There is currently no process for re-encrypting existing data with old and new master keys.
Back up the database and encryption key together. Restore first with the application version and key that match the backup.
Review key and backup requirements →
Versions and image tags §
| Tag | Meaning | When to use it |
|---|---|---|
| 2.0.0-rc.2 | Exact version tag without the Git tag's v prefix | Use it to pin a version; production can also pin an image digest |
| 2 | Floating 2.x channel; before GA it may track verified 2.0 Beta and RC releases, and after GA it tracks stable 2.x only | Use when accepting new versions that pass the release gates |
| 2.0-beta | Tracks only strictly formatted 2.0 Beta releases, not RCs | Use only when you want to stay on the Beta channel |
| 2.0-rc | This floating tag does not exist; RCs use exact tags and may also advance 2 before GA | Do not configure it |
| latest | Remains on 1.x and does not represent 2.x | Do not use it for 2.x deployments |
Database migrations are one-way. A rollback requires restoring the pre-upgrade database and matching keys, not just changing the image tag.
Review deployment and upgrade steps →
Maintenance policy §
- Before GA, 2.0 is a pre-release security-supported candidate. Release readiness is determined by actual Releases and artifacts.
- 1.4.x is in maintenance and accepts only security and critical bug fixes, with no new features.
- There is currently no published 1.4.x EOL date or fixed 2.0.x support period. Follow official release announcements for future policy.