Troubleshooting

Find the error you are looking at. Each entry says what happened and what you should do.

The portal and the client word things differently

The same underlying cause can show slightly different text in the portal and in the client. The entries below are grouped by cause.

Device grants

Signing service unavailable

What it means: your action was recorded, but the backend component responsible for issuance could not complete delivery this time. This is a temporary server-side state, not something you did wrong. The system is fail-closed — it will not fake a success.

What to do, depending on when you hit it:

• While approving — the approval is recorded but not yet issued. Go to the Authorized list on the portal's Device grants (「设备授权」) page later and click Retry issuance (「重试签发」) for that device. The retry reuses the same grant sequence number and does not consume quota twice.
• While revoking — the revocation was not delivered; neither the grant nor the quota changed. Retry later with a fresh account code — revocation is safe to submit repeatedly.

The message usually carries a reason in brackets; include it when you report the problem.

Do not keep clicking approve

Every attempt can leave a record behind, which makes hitting the quota ceiling more likely. Use Retry issuance rather than starting a new request.

Quota exceeded

What it means: you (or the whole account tree) have used up an allowance. Work out which one first:

Allowance	When you hit it
Device grants	Requesting or approving a device grant
Registered devices	A new device signs in to the account
Concurrent sessions	Too many remote sessions open at once
Sub-accounts	An administrator creates a new member account

What to do:

1. Look at pending requests first. Pending already books a slot, and rejecting frees it immediately — usually the fastest fix. Go to the portal's Device grants page and reject the requests that should not proceed.
2. Revoke grants you no longer need — the slot is freed once the revocation is confirmed.
3. If it is concurrent sessions, close the session tabs you are not using.
4. If cleaning up is still not enough, your real usage has outgrown the current plan — contact your administrator or sales to add capacity.

Expired grants do not occupy slots

A grant that reaches its 30-day expiry frees its slot automatically, with no manual clean-up. The two states that occupy slots are pending and authorized.

Records that "still occupy quota"

If a record shows that the signing service rejected it but it still occupies quota, revoke it to free the slot.

Invalid account code

Three different causes, three different fixes:

Message	Cause	What to do
Account code is incorrect	Mistyped, or the wrong credential	Read the code from the authenticator again; make sure it is the account code, not the keymachine operator code
That code was just used	The same code cannot be used twice	Wait for the next 30-second code
The account code needs re-enrolling	The enrolment is no longer valid	Re-enrol the authenticator in the portal at /account/profile, My account → Security
Too many attempts, temporarily locked	Repeated failures triggered protection	Wait for the lock to clear, then retry

Check the phone's clock first

Apart from typos, the most common cause is device clock drift — authenticators generate codes from the current time, so a phone with the wrong time will never match. Set the phone to sync time automatically.

Account owner or administrator approval required

What it means: the signed-in account is not the tenant's owner or an administrator. Only owners and administrators can approve, reject or revoke device grants; other roles can only view.

This is not a problem with your code — retyping a different one will not help.

What to do: have the account owner or an administrator sign in and do it.

Device grants not enabled

What it means: the device-grant issuing chain is not enabled for your service — the server side has not configured the issuance channel yet. This is not a problem with your account or your device.

In this state the portal's Device grants page shows this notice permanently, the list is empty, every action button is disabled, and only a re-check action remains.

What to do: contact your administrator or service provider to enable it. There is nothing to fix from the user side — this is deliberate fail-closed behaviour.

This device is already authorized

What it means: not an error. This device already holds a grant in effect; a duplicate request is ignored idempotently and consumes no quota.

What to do: nothing — just connect.

Request expired / request state changed

What to do: refresh the list. If you still need access, have the controller submit a fresh request.

The signing service rejected this request

What it means: the request has been handled as rejected.

What to do: refresh the list, and have the controller request again if needed. Contact your administrator if it keeps happening.

Too many attempts / issuance channel busy

What to do: wait a while and try again.

Connections

Approved but still cannot connect

After approval the grant has to be issued and delivered; hosts sync about every 30 seconds, so it takes effect at most about 60 seconds later. If it is clearly longer than that:

1. Confirm the grant in the portal shows Authorized, rather than sitting at Awaiting issuance;
2. Confirm the target machine is online — check its last-seen time in My devices;
3. Confirm the target machine's Control permission column shows Enabled v4 (see enabling a host);
4. If all of that is right and it still fails, see signing service unavailable above.

Connected but the screen is black (macOS host)

This is almost always the Screen Recording permission.

1. On the host machine: System Settings → Privacy & Security → Screen Recording, and confirm FortSwift is ticked;
2. Quit FortSwift completely and reopen it — macOS only reads this permission at process start, so ticking it without restarting is the same as not ticking it;
3. Confirm the machine is not in a state that turns the display output off.

TIP

Apple does not allow an app to grant these permissions itself; it can only send you to System Settings. The host console in the client can check each item's current state.

Picture is fine but the mouse and keyboard do nothing (macOS host)

This is the Accessibility permission. Screen Recording covers "can be seen"; Accessibility covers "can be driven". They are separate.

Tick FortSwift under System Settings → Privacy & Security → Accessibility, then restart the app.

Windows host will not connect

Screen capture and input injection on Windows need an interactive logged-in session. Confirm a user is signed in on that machine.

Cannot open another session tab

There are at most 8 concurrent sessions. Close a tab you are not using and try again. If the message mentions quota, see quota exceeded.

Sessions stutter or lose quality

Start with the network — upstream bandwidth and jitter matter more than raw bandwidth. See remote sessions.

Sign-in

Password sign-in is disabled for this account

The account has a passkey enrolled, which switches password sign-in off automatically. Sign in with the passkey.

Browser does not support passkeys

Use an up-to-date Safari, Chrome or Edge.

Lost the passkey

Re-add it with the one-time recovery codes you saved at enrolment. They are shown once, 10 of them. If they are all used or lost, contact your administrator.

Every device asks me to sign in again after an upgrade

This is expected — some security upgrades invalidate all existing sessions. Just sign in again.

Installation

macOS says it cannot open the app

The package is Developer ID signed and notarized by Apple. If the system still blocks it, verify the SHA-256 checksum first to confirm you downloaded the official package.

Windows SmartScreen warning

Verify the checksum first, then decide whether to continue.

Still stuck

Contact your team's administrator, or email support@fortswift.com. Please include:

• the client version and platform;
• the exact error text (including the reason in brackets);
• roughly when it happened, with the time zone;
• the device name of the target machine.

Never put a code in the email

Do not send your account code, the keymachine operator code or recovery codes to anyone — us included.