Troubleshooting
Fixes for common Keygate problems: missing login codes, Stripe purchases without a license, ACTIVATION_LIMIT, SEAT_PAUSED, DEVICE_HELD and seat limits.
Most problems people run into with Keygate come down to a handful of settings. Start with the server log: Keygate says what it refused and why.
Signing in
Why don't I receive the login code?
If no email provider is set up, Keygate writes the code to the server log instead; with Docker run docker compose logs keygate | grep "OTP code". If email is set up, use Send Test Email in the email settings to check it. Each address can request three codes every ten minutes, and each code can be tried five times before a new one is needed. And if sign ups are limited to emails that hold a license, an unknown address gets no code at all, on purpose.
Why does the code work but I stay logged out?
When BASE_URL starts with https, Keygate marks its login cookie as secure, and browsers drop secure cookies on plain http pages. This happens when you open Keygate by IP address or over http while BASE_URL says https, for example before the reverse proxy is set up. Open Keygate at the address in BASE_URL. If your proxy talks to Keygate over plain http, that is fine as long as visitors reach the proxy over HTTPS.
Why won't Keygate start?
Keygate checks its settings at startup and stops if one is missing or wrong, and the log names it. The usual causes are a JWT_SECRET shorter than 32 characters, a LICENSE_SIGNING_KEY that is not exactly 64 hex characters, an ENVIRONMENT other than development, staging or production, and storage settings filled in only partly.
Why does Keygate stop with another instance has been migrating for over 10m0s?
On startup Keygate takes a lock before it migrates the database, so that only one instance migrates at a time, and waits up to ten minutes for it. This message means the lock was still held after that. Usually another instance is in the middle of a long migration: wait for it to finish, then start this one again. If no other instance is running, a connection pooler in transaction mode is the likely cause; point Keygate at PostgreSQL directly or use session pooling.
Payments and sign ups
A customer paid in Stripe but no license appeared. What went wrong?
Look in the server log. stripe webhook auto-setup failed means Stripe cannot reach BASE_URL, which has to be a public HTTPS address. could not resolve plan means the price that was bought is not set on any plan; add the price ID to the plan so future purchases work, and use Issue License for the customer who already paid. Also check that the install and the purchase use the same mode, test or live.
Why doesn't a customer see the Upgrade button?
Upgrade shows only to the owner of a license on a free plan, one with no Stripe price, update period or renewals, that Stripe does not bill already and that is not suspended or revoked. Stripe must be connected, and the product needs an active plan with a Stripe price that is not a trial and does not sell an update period.
Why does Cancel and revoke answer STRIPE_UNAVAILABLE or STRIPE_NOT_CONFIGURED?
Cancel and revoke cancels the subscription in Stripe before it touches the license, so a customer is never left paying for a license that was taken away. 502 STRIPE_UNAVAILABLE means Stripe did not confirm the cancel; nothing was changed, so try again. 503 STRIPE_NOT_CONFIGURED means the install has no STRIPE_SECRET_KEY. The action never refunds money; make refunds in the Stripe dashboard.
Why does the sign up form say the plan is full?
The plan has reached its daily sign-up limit. The count starts again at midnight UTC, and the API answers 429 SIGNUP_LIMIT_REACHED with a Retry-After header until then. Raise the limit on the plan, or set it to 0 for no limit.
License checks
Why does activation fail with ACTIVATION_LIMIT?
Every device slot on the license is taken. All devices count toward one limit, whichever key activated them, the owner's or a team member's. On a plan sold per seat the limit is the plan's max activations for each seat bought. The customer can free a slot in the customer portal, or your app can call deactivate on the old device. If this happens to customers who only use one computer, your app is probably sending an identifier that changes between runs, so every start looks like a new device.
Why does activation fail with SEAT_PAUSED?
The key belongs to a team member who is paused. A license can hold more people than its seat limit when the limit goes down after people joined: an admin lowered the plan's max seats, the seats bought or the plan were lowered in Stripe, a trial moved to a free plan with fewer seats, an undone upgrade took the license back to its free plan, or an upgrade to Keygate v0.1.17 left a plan at max seats 1, which now holds the owner alone. The owner counts as one seat and is never paused; of the members, those who joined last wait. Verify answers 404 LICENSE_NOT_FOUND for the same key in the meantime. To fix it, the owner removes a member or gets more seats, or you raise the plan's max seats. The paused member's key works again at once, with nothing else to do.
Why does activation fail with DEVICE_HELD?
A team member's key was used on a device that is already activated on the license with another key: another member's, or the owner's license key. A device stays with the key that activated it. The owner can remove the device in the customer portal, or the other person can deactivate it from their app; after that the member activates it with their own key. Devices activated with the owner's key before Keygate v0.1.17, when members shared that key, are not refused: they move to the first member who activates them with their own key.
Why does activation fail with FLOATING_LICENSE?
The license is on a floating plan, and floating seats are taken with /license/floating/checkout, not with activate. Switch the app to checkout, heartbeat and checkin as described in Floating licenses. Verify answers the same for a device that was activated before the plan became floating: it no longer gets a token.
Why does floating checkout fail with SESSION_HELD?
The machine already has a running floating session that was checked out with another key on the license, the owner's or another member's, and a member's key can only renew its own sessions. Check the session in with the key that took it, or wait until it times out; the machine then goes to whoever checks it out next.
Why does verify return LICENSE_NOT_FOUND for a key that exists?
Verify answers the same way whether the key is unknown, unusable or not activated on this device, so that keys cannot be guessed. The most common reason is that this device was never activated, so call activate first. With a team member's key, verify only accepts devices that key activated, and it fails while the member is paused or after they were removed from the license. Otherwise the license may be suspended, revoked or expired, which the license page in the dashboard shows.
Why does my app get 429 LOCKED_OUT?
Five failed license calls from one IP address within five minutes lock that address out, for 30 seconds the first time and twice as long each time after that, up to 30 minutes, until 30 minutes pass without a lockout or a call from that address succeeds. It usually means someone is guessing keys, or your app is retrying a wrong key in a loop. The limits can be changed with BF_MAX_FAILS and BF_LOCKOUT_SECONDS. If everyone behind your proxy is locked out together, Keygate sees the proxy's address for all of them: see the client's address under Installation.
Members, seats and plans
Why can't a member accept their invitation (SEAT_LIMIT)?
Every seat on the license is taken. A pending invitation holds a seat when it is sent, so this happens when the seat limit went down after the invitation was sent, for example when an admin lowered the plan's max seats or the seats bought were lowered. The invitation stays valid until it expires, seven days after it was sent. Once the owner removes a member or gets more seats, the invitee opens the same link again. Inviting someone while every seat is taken answers SEAT_LIMIT too, with details.max and details.current, both counting the owner.
Why does lowering seats or changing plans fail with SEATS_IN_USE or DEVICES_IN_USE?
Keygate never removes people or devices to make a change fit, so a change that would leave fewer seats than people, or fewer devices than are activated, is refused. SEATS_IN_USE counts the owner, the members and pending invitations; DEVICES_IN_USE counts activated devices, or running sessions on a floating plan. The answer's details says how many are in use and what the new limit would be. Remove members or cancel invitations in the customer portal, remove devices there, or let floating sessions end, then try again. It applies to lowering the seats bought in the portal or with the admin API, to a downgrade in the portal, and to Change Plan in the dashboard, which checks seats.
Why can't I edit or delete a plan (TRIAL_FALLBACK_IN_USE)?
The plan is the fallback of one or more trial plans: their licenses move to it when their trial ends. A fallback has to be a free plan that is not a trial, so while trial plans name it, it cannot be deleted, turned into a trial or given a Stripe price, an update period or renewals. The message and details.plans name those trial plans. Choose another fallback on them, or none, then change this plan.
Webhooks and updates
Why aren't webhooks delivered to my local receiver?
Keygate refuses to deliver to private, loopback and link local addresses so that a webhook cannot be used to reach your internal network. For a receiver on the same machine or Docker network, set WEBHOOK_ALLOW_PRIVATE=true.
Why do I receive quota.exceeded over and over?
It is sent for every usage call the quota refuses, not once when the quota runs out. If your app keeps reporting usage after 429 QUOTA_EXCEEDED, each call sends another one. Stop reporting until the period resets, or deduplicate by license and feature on your side.
Why does the update feed answer 401 LICENSE_KEY_REQUIRED?
The product requires a license on its feeds. The updater has to send the license key in an X-License-Key header, or the signed token from verify in an X-License-Token header or as license_token in the URL.
Why do releases answer STORAGE_DISABLED or SIGNING_DISABLED?
Release hosting and signing need S3 compatible storage and an encryption key for the signing keys. Set STORAGE_BUCKET, STORAGE_ACCESS_KEY, STORAGE_SECRET_KEY and RELEASE_KEY_ENCRYPTION_KEY, plus STORAGE_ENDPOINT for anything other than AWS S3, and restart Keygate. With any of them missing, signing stays off and the signing pages answer SIGNING_DISABLED.
API keys and settings
Why does my API key get 403 PRODUCT_SCOPE_MISMATCH?
The key is bound to one product and the request named another one, or a license or release that belongs to another product. Lists and the license export narrow to the key's product on their own when you leave product_id out. Admin keys cannot be bound at all: creating one with a product answers 400.
Where did the rate limit, webhook and quota warning settings go?
They were never read from the dashboard, so they were removed. Set them with the environment variables RATE_LIMIT_API, RATE_LIMIT_ADMIN, WEBHOOK_MAX_ATTEMPTS, WEBHOOK_HTTP_TIMEOUT and QUOTA_WARNING_THRESHOLD, then restart Keygate.
Analytics
Why do the analytics charts start their days at a different hour from mine?
Activations and usage are counted per UTC day, the same days the date range is chosen in. Someone east of UTC sees a late evening activation on the next day's bar, and someone west of UTC sees an early morning one on the day before.
Still stuck? Ask in GitHub Discussions with the relevant lines from the server log.
Last updated October 27, 2026