Troubleshooting

Failure modes by where they are noticed, what each looks like, and where to read the cause. Every HTTP response carries an X-Correlation-Id; quote it and an operator finds the request's Server log lines and Audit Log rows at once.

The Server will not start

Every refused start is one Critical line naming the cause. The full table is on Server installation. The short version:

Symptom	Cause
A line naming KeyRingProtector:	No protector, not base64, wrong password, or no RSA key. Every deployment needs one.
…the Key Ring Protector configured here opens none of them	A swapped protector. Restore the old one, or add it under RetiredCertificates.
Certificates:Validation:License is not configured	No PKI licence. Every deployment needs one since Server 1.7.0, vault or not. An expired one does not stop the start; see the next table.
This Server's database did not answer in N seconds	The database never answered at start. Check ConnectionStrings:TrustBridge and that the database is running. On Azure SQL, check public network access or the private endpoint (error 47073).
…is behind the build … by N migration(s)	MigrateOnStart is off and migrations are pending.
…has N migration(s) applied that this build does not contain	An older image on a newer schema: a rollback without restoring the pre-upgrade backup. Or a database created by Server 1.2.0 or earlier.
A line naming ForwardedHeaders:TrustedProxies	A malformed proxy list: given as a single value instead of indexed (ForwardedHeaders__TrustedProxies__0), /0, host bits past the prefix, an IPv4 address not in plain dotted decimal or in IPv6 form, a link-local address, another key under ForwardedHeaders such as KnownProxies, or the list set together with ASPNETCORE_FORWARDEDHEADERS_ENABLED. The line names the entry.
Admin:CertificateSignIn:Enabled is on, but Admin:CertificateSignIn:WebPkiLicense is not set…	Certificate Sign-In needs the Web PKI licence, in its one-line format, naming the hostname people type.
Admin:CertificateSignIn:Required is on, which switches passwords off, but Admin:CertificateSignIn:Enabled is off…	Passwords off with no certificate sign-in would leave no way in. Turn one of the two the other way.
Workstations:ClientTimeout of … is shorter than 00:00:10… or …longer than 00:05:00	Out of range, usually a unit mistake. Write it as hh:mm:ss: a bare 15 is fifteen days.
Signer:ApiKey is required…	A Signer address with no key.
RestPkiCore:… is required when any RestPkiCore key is set, …must be an https address…, …must end in a slash… or …must be a GUID naming a security context…	The RestPkiCore section is all three keys or none, with an https endpoint ending in a slash and a GUID for the security context. The line names the key.
Signing:StrandedAfter must be greater than twice Signing:RequestBudget plus Signing:SignerCancelBudget…	Since Server 1.18.0 the floor is higher. Raise StrandedAfter above that sum; the defaults clear it.
Dashboard:TimeZone names '…', a Windows time zone id… or …which is not a time zone this Server knows	Name an IANA zone, such as America/Sao_Paulo, or UTC.
Database:Engine is '…', which names no engine this Server runs on… or …but ConnectionStrings:TrustBridge is written for …	The engine key and the connection string disagree, or the key names neither SqlServer nor PostgreSql. A deployment chooses its engine once; see Configuration.
SpellThumbprintsUpperCase: … holds rows whose thumbprints differ only in case…	Server 1.20.0's migration on a SQL Server database with a case-sensitive collation. Nothing was changed; the line names the table and what to do with each pair.
Sessions:MaxDuration below DefaultDuration, or another cross-key rule	A refused configuration; the line names both keys.
On App Service, the container is killed and restarted in a loop with nothing useful logged	A migration outlasting WEBSITES_CONTAINER_START_TIME_LIMIT (230 s default). Set it to 1800.

The Server started but does not work

Symptom	What it is	Where to look
/ answers 200, /healthz answers 503	The database went away after start. The contract fails; the vault is closed.	The connection string, the database's availability.
Every vault signature and import is refused while workstations sign fine	The vault latch: the Server came up before its database.	The VaultReadiness warning at start. It opens on the first use once the database answers.
A banner on every admin page: This Server's PKI licence was refused: no Vault Certificate can sign, and no workstation will once it restarts	The licence is expired, garbled or not a licence, or a read-only filesystem with no writable /tmp kept the SDK from reading it. No Vault Certificate can sign, and imports are refused. A workstation can no longer sign once its Workstation Service restarts; until then it keeps signing only if it still holds an earlier licence the SDK accepts.	The LacunaPkiRuntime Critical line at start and the Error line beside it. Renew the licence and restart the Server; mount a tmpfs over /tmp on a read-only filesystem.
Every Vault Certificate reads UNTRUSTED although the licence is current	No anchor can terminate a chain: UseIcpBrasil off with no Trusted CA that is a root.	The anchor-set Critical line, which says no anchors are configured.
Sessions of one Client Application answer 422 WORKSTATION_OFFLINE since Per-Transaction PIN was turned on for it	The holders' machines are still on Workstation 1.5.0 (protocol 5), which cannot ask for the PIN per call.	Warning lines naming each machine passed over at protocol 5. Upload and offer Workstation 1.6.0, or turn the switch off until the fleet has it: see Rollout order.
Since the upgrade to Server 1.17.0 or later, sessions no longer end after their usual number of signing calls	Sessions:SignatureAllowance is no longer read: the allowance is each Client Application's now, and none has one after the upgrade. A Warning at start names the key.	Set the Signature Allowance on each Client Application that needs one, then remove the key. See Upgrading to Server 1.17.0 or later.
The Dashboard says Nothing is settled yet, or the status strip reads Signing Activity not settled yet	Signing Activity has not been counted for the first time: on the first start of Server 1.17.0 or later it is back-filled from the whole Audit Log first.	Wait for the back-fill. If it never settles, the Dashboard says so and the Server log says why.
The status strip reads Signing Activity stopped at …, and the Dashboard heads What needs you with it	The Dashboard's count has stopped advancing, and every figure ends at that moment. A Test Signature still running holds it on purpose until it ends.	The Server log: the Signing Activity … and Audit retention purge is held at … lines. See Warnings worth an alert.
The Audit Log keeps rows older than Audit:RetentionDays	The purge never deletes what Signing Activity has not counted: it waits for the first back-fill, and for a count that is behind.	The Audit retention purge lines in the Server log.
Sign documents with REST PKI Core is refused: REST PKI Core is not configured on this Server (the RestPkiCore section)…	The deployment has no RestPkiCore section.	Configure RestPkiCore:Endpoint, ApiKey and SecurityContextId and restart; see Configuration.
Every signing call of an application switched to REST PKI Core answers 500 INTERNAL_ERROR	REST PKI Core refuses the key, the key's application lacks the Worker role, the security context does not exist there, or the RestPkiCore section was removed after the switch.	The Error line naming which, from …Signatures.RestPkiCoreAdmission. Fix it, or switch the application back to the Signer.
REST PKI Core documents sign, but every fetch fails with 502 SIGNER_ERROR, or 500 INTERNAL_ERROR with an Error line	A signed document is downloaded from REST PKI Core's own site address, which is not necessarily the configured endpoint, and the Server cannot reach it.	Let the Server out to the instance's site address as well as to RestPkiCore:Endpoint.
REST PKI Core refuses holders' certificates as 422 CERT_NOT_ACTIVE that this Server trusts	Trust on that path is also the REST PKI Core security context's, which is kept apart from the Trusted CAs screen.	A custom security context that trusts the holders' CAs, kept in step with the Trusted CAs by hand.
Documents signed with REST PKI Core carry no ICP-Brasil policy, or have marks on their pages	The signature policy and the page marks are REST PKI Core's instance and subscription settings, not this Server's.	On REST PKI Core's side: General:UseBrazilianPdfSigningPolicies on and General:DefaultSignaturePolicy at Basic for AD-RB, and the subscription's PDF marking policy at Never for no marks.
A machine's Report chip reads Not reported	It runs a release before Workstation 1.8.0, its deployment turned reporting off, or its last report was sent by another version than the one it runs now.	The detail panel's Workstation Report section says which.
The status strip shows N update required	Machines whose protocol the Server no longer accepts. On Server 1.15.0 and later, Workstation 1.4.x or older.	The fleet screen's Service version column. Install the current release on them by hand or by Group Policy.
A machine's Console Account cell reads Needs Workstation 1.10.0	It runs a release before Workstation 1.10.0, which does not report its console. Nothing is wrong with it.	Offer it Workstation 1.10.0 or later, which goes with Server 1.20.0 or later and shows its console from Server 1.23.0.
A machine's Console Account cell reads Not reported	Its reporting is off, or it has not sent a report since it began running the version it runs now.	The panel's At the console section says which. A machine whose deployment turned reporting off never says who is at its console.
Every Test Signature fails at the loopback step, or the log says POST /v1/sessions answered 400 with no error envelope	The run cannot reach the Server's own /v1: on Docker the Server listens on HTTPS alone with a certificate localhost does not match, or AllowedHosts does not admit the loopback's host.	Add http://localhost:8080 to ASPNETCORE_URLS, and the loopback host to AllowedHosts: see The Test Signature.
A Test Signature through a reverse proxy ends in the proxy's 502, 504 or 524	The proxy stopped waiting before the run ended.	Keep TestSignature:MaxTimeout below the proxy's read timeout, or type a shorter timeout.
Deleting a Workstation Release takes minutes on Azure SQL	A small database (Basic, 5 DTU) writes the package to its transaction log slowly. Since Server 1.16.0 the delete has ten minutes.	Wait for it; the screen says it has started.
A setting has no effect	One of the seven overridable keys was saved on the Settings screen, and the database layer wins silently.	/admin/settings; restore the deployed defaults.
Admin console at http:// never completes a login	A cookie without Secure over a link the platform upgrades.	On App Service, --https-only true. Behind your own TLS proxy, name it in ForwardedHeaders:TrustedProxies and have it pass X-Forwarded-Proto.
Behind a proxy, the login redirect points at http:// or at the upstream address	The proxy replaces X-Forwarded-Proto with http, or does not pass the browser's Host through.	nginx: proxy_set_header Host $host, and keep the edge's X-Forwarded-Proto.
Every audit row records the proxy's address	The proxy is not named, so every caller is the proxy. Behind an unnamed proxy all browsers also share one Certificate Sign-In bucket and the whole fleet one admission bucket.	Docker: ForwardedHeaders:TrustedProxies. App Service: ASPNETCORE_FORWARDEDHEADERS_ENABLED=true. The start line beginning Forwarded headers: says what is trusted.
A Warning at start: Forwarded headers: honoured from whoever connects …	A Docker deployment still using ASPNETCORE_FORWARDEDHEADERS_ENABLED: any client that reaches the port can name its own address.	Name the proxy in ForwardedHeaders:TrustedProxies and unset the variable.
Machines' disconnects read closed on LongPolling; the admin console is sluggish	The proxy does not carry WebSockets, so connections fall back to long polling.	The proxy's WebSocket upgrade headers.
KeyRingProvider[48] or XmlKeyManager[24] lines on a Server that started cleanly	The database is unreachable, not the protector.	/healthz.
A Critical line carrying a whole audit row	The database refused an audit write; the row lives only in this line.	Keep the log stream. The console shows an alert.
A warning banner on every admin page about the test CAs	UseLacunaTestPki is on.	Turn the test PKI off on anything but a development box.

A Test Signature that failed at the signature step

Since Server 1.24.0, a Test Signature that failed at the signature step follows the step's sentence with one chosen by the contract's code, and shows the code and the contract's answer beside it. A batch says it for each document that did not sign.

Code	What it is	What to do
CERT_INCOMPLETE_IDENTITY	The certificate does not name its holder well enough to sign under them.	If what it lacks is an e-mail address, type one in E-mail address. Any other field is the certificate's own.
PIN_NOT_AVAILABLE	The holder's PIN could not be used: most often declined or not answered at the Tray App, or a locked token.	The contract's answer says which.
SIGN_TIMEOUT	The signature did not finish in time. The holder's key may already have signed.	The contract's answer says whether it had; if so, signing again signs again.
TOO_MANY_PIN_ATTEMPTS	The CPF lockout: too many wrong PINs for this holder recently, so the PIN was not checked.	Wait for the oldest attempts to age out of the window.
INVALID_PIN	The PIN the signature was sent with is wrong.	Type the right PIN.
SESSION_EXPIRED	Another session for the same holder replaced this one, or its window passed.	Run it again.
WORKSTATION_OFFLINE	The machine holding the certificate is not connected, runs a release too old to ask its holder, or was removed.	The Workstations screen.
CERT_NOT_ACTIVE or CERT_NOT_FOUND	The certificate is expired, revoked or untrusted, or its token is not on the machine; or it is no longer held on the platform.	The Certificate Registry.
CERT_DATA_UNAVAILABLE	The Server holds no copy of the certificate itself, which signing needs: the machine holding it may run a Workstation Service too old to send one.	Upgrade the machine; it sends the copy once it reconnects.
No code	The timeout passed during the signing call, which waits for the holder to confirm at the Tray App under Per-Transaction PIN.	Type a longer timeout, and have the holder confirm at the Tray App.
Any other code	The contract refused the signature with that code.	See Client application errors.

Signing in to the admin console

Symptom	What it is	What to do
No certificate with a CPF was found on this computer	Only e-CPF certificates are listed: an e-CNPJ or a certificate without a CPF is never offered. Or the token is not plugged in.	Insert the token or card holding the e-CPF and reload the page.
Every certificate on this computer has expired	Only expired e-CPFs were found; they are listed under Expired, greyed, and cannot be chosen.	Insert the token or card holding a valid e-CPF and select Refresh list.
The login page opens on the certificate page	This browser last signed in with a certificate, and the login page remembers the way in.	Select Password at the top of the page.
Signing in with a certificate is available on a computer only	A phone or a tablet.	Use a desktop browser.
…needs the Web PKI component, which is not installed in this browser or …has to be updated	Web PKI is missing or outdated in this browser.	Follow the page's Install Web PKI or Update Web PKI.
Certificates cannot be read here: this Server's Web PKI licence does not cover this address	Admin:CertificateSignIn:WebPkiLicense does not name the hostname people type, or is not valid.	A Web PKI licence for that hostname, then restart.
That sign-in did not open an account	No enabled account holds the certificate's CPF as its Bound CPF.	Another Administrator sets the person's CPF with Set Bound CPF on the accounts screen. Nobody can set their own.
This Server does not trust the authority that issued this certificate, or a sentence saying it expired, was revoked or could not be checked	Only an ACTIVE verdict signs in. UNTRUSTED is usually the administrators' Trusted CA removed, or the Server's PKI licence refused (the admin console shows a banner).	The Trusted CAs screen counts the administrators each authority signs in before you remove it; renew the licence.
This certificate does not name a valid CPF as its holder	A Company's certificate.	Sign in with the person's e-CPF.
Too many attempts from this address	Ten challenges a minute per address. Behind an unnamed proxy, every browser shares that bucket.	Wait a minute; name the proxy in ForwardedHeaders:TrustedProxies.
Passwords are off and an account has no Bound CPF	It cannot sign in at all while Admin:CertificateSignIn:Required is on, new accounts included.	Another Administrator sets its Bound CPF. A lone Administrator has nobody to set theirs, so keep at least two.
Passwords are off and nobody can sign in	Everything that ends every certificate sign-in at once: the administrators' Trusted CA removed, a refused PKI licence, a Web PKI licence that no longer names the hostname, a browser update that broke the extension, or the last Administrator's Bound CPF cleared.	Set Admin:CertificateSignIn:Required=false and restart; sign in with a password and fix the cause; then set it back to true and restart. Nothing reminds you to undo it.

Workstations

Symptom	What it is	Where to look
Install exit code 1603, log names SERVER_URL	The launch condition: empty or scheme-less URL.	Pass SERVER_URL=https://….
Install exit code 1603, log says a newer version is installed	A downgrade.	Uninstall first; the machine returns as a new one.
Install rolls back at Starting services	The service refused to start: an INSTALLER_KEY that will not parse, or a registry value of the wrong type.	Application event log, source TrustBridge Workstation Service.
Unknown publisher on the elevation prompt, a SmartScreen hold, or a publisher-requiring policy refusing the package	An unsigned package: a development build, never a release. Every Workstation release from 1.2.1 on is signed by LACUNA SOFTWARE LTDA.	Get the release package from Lacuna Software and check its signature with Get-AuthenticodeSignature.
Installed, never appears in the admission queue, nothing on the Server	The Server URL is wrong, or a GPO is overriding it, or the TLS chain is not trusted by the machine.	The service's Server:Url is …, supplied by … line at start; HKLM\Software\Policies\TrustBridge from a 64-bit PowerShell.
Never appears, and the machine's log says its admission request was refused	One of four: revoked, an Installer Key the Server does not trust, too many requests from its address, or a full queue. The Server deliberately does not say which.	The last two clear themselves. Check the fleet screen for a revoked row: its key is refused for as long as that row stands.
A machine that was removed is back in the admission queue	It is still installed and asked again, so it arrives as a new machine under a new id.	Admit it if it belongs in the fleet; otherwise uninstall it and let the request lapse. A machine that must stay out is revoked, not removed.
A machine sent back to the queue stays there indefinitely	A machine admitted once and returned to Pending never lapses.	Remove on its admission queue row.
In the queue, Tray says Admission pending	Not a fault.	Admit it at /admin/admission.
Admitted, but does not connect; Server log says …is newer than this server's supported window …; update the Server first	The workstation was upgraded ahead of its Server, for example Workstation 1.6.0 against a Server before 1.15.0. It gets no licence, so every certificate on it reads UNTRUSTED.	Upgrade the Server. See Rollout order.
Admitted, but does not connect; the fleet row says …is older than this server's supported window …; update required	The workstation is too old for the Server: on Server 1.15.0 and later, Workstation 1.4.x or older.	Install the current release by hand or by Group Policy. The Server cannot update it.
Admitted, but does not connect; Server log says A workstation assertion was refused: Expired or NotYetValid	The machine's clock is more than 60 s out. The line gives the offset: positive when the machine is behind the Server.	Time synchronisation on the machine.
Connected, but its holders' sessions are answered WORKSTATION_OFFLINE	For a Client Application with Per-Transaction PIN on: the machine runs Workstation 1.5.0, which cannot ask per call. (On Server 1.13.0 or 1.14.x, a machine on 1.4.x is sent no PIN challenge at all.)	Offer it Workstation 1.6.0 or later.
A machine on Workstation 1.8.0 keeps being disconnected by a Server before 1.20.0	Its Workstation Report is larger than an earlier Server's workstation channel takes (32 KB), which a machine with many tokens, middleware or errors can send. Workstation 1.8.1 fixed it: until the Server has taken a report on a connection, it keeps its reports under 32 KB.	Upgrade the Server to 1.20.0 or later, which takes up to 1 MB, or move the machine to Workstation 1.8.1 or later. Deliver Workstation 1.8.0 and later with Server 1.20.0 or later all the same, the first that takes the report.
A per-transaction signing call answers PIN_NOT_AVAILABLE with no Tray at the console	The machine had no Tray App it could ask: nobody signed in at its console, a holder on Remote Desktop, no Tray App running there or one older than 1.6.0, an update being installed, or a Tray that stopped answering.	The machine's Events tab says which, in words (Server 1.23.0), from Workstation 1.9.0 on; so does the detail of its signing.authorization-refused row in the Audit Log (Server 1.22.0). See Why no Tray App could be asked. The client is told nothing more.
Session creation answers PIN_NOT_AVAILABLE, and the machine's Events tab says No A1 PIN is set for the A1 Certificate on the machine. under Session-start PIN prompt refused	Every certificate the prompt could offer on that machine is an A1 Certificate with no A1 PIN set (Workstation 1.10.0, Server 1.23.0). Its pin.prompt-answered row reads Undeliverable with detail NO_A1_PIN.	Ask the holder to set an A1 PIN for the certificate in the Tray App on that machine.
A machine's Console Account cell reads an account with no Tray, or it is under Console Account, no Tray	Somebody is signed in at the console and no Tray App runs in that session, so every PIN prompt sent to the machine is refused.	Ask the person at the machine to open TrustBridge from the Start menu (Workstation 1.9.0 and later); on an earlier release, to sign out and in again.
After a PIN prompt closed, the Tray App's icon is gone, per-transaction calls answer PIN_NOT_AVAILABLE with no Tray at the console until sign-out, and starting the Tray App again does nothing	A defect before Workstation 1.8.1: a PIN prompt closing in a Tray whose window had not been opened since sign-in ended the Tray, and its exit hung, so no new Tray could start in that session.	Sign out and in again. Deliver Workstation 1.8.1 or later, where a closing prompt no longer ends the Tray and its exit cannot hang.
The holder's Tray App is gone or does not answer	It was closed, crashed, hung, or was ended by a repair.	Ask the holder to open TrustBridge from the Start menu (Workstation 1.9.0 and later). It brings the running Tray's window forward, or starts one; a Tray that does not answer within 5 s is ended and replaced, in that Windows session only, and the replacement is logged at Error, which reaches the Workstation Report. Before 1.9.0, sign out and in again.
Opening TrustBridge from the Start menu says The Tray App is already running in your Windows session, but it is not responding and could not be closed.	A Tray that does not answer could not be ended, and is left running.	Sign out of Windows and sign in again.
The Tray App's Change Server… button is disabled, and the address reads (set by Group Policy)	The Server URL comes from Group Policy, which a repair could not override.	Change the URL in the policy.
Every certificate reads UNTRUSTED	No PKI licence reached the machine: it is Pending, has not reached its Server, is refused with update the Server first, or the Server's own licence is refused (the admin console shows a banner). Or no anchor can terminate a chain.	The Tray App's line above the certificate list says which. Admit the machine; renew the licence on the Server and restart the Server, and the machine applies it when it reconnects. Nothing set on the machine supplies a licence.
A certificate reads UNTRUSTED while the licence is fine	Its issuer is not in the machine's anchor set.	Trust the issuer on the Certificate Registry, which adds a Trusted CA that reaches the machine.
A certificate reads STALE	Its CA's CRL could not be fetched for longer than the grace window (24 h).	The CA's reachability from the machine.
A token is plugged in but no certificate appears	Uncommon middleware not in the shipped list; or a module named in Certificates:Pkcs11:Modules that will not load.	The Tray App's Tokens tab names the middleware that failed and any reader holding a card no middleware reads. The service log names the module.
The Tokens tab says Windows could not start a smart-card reader. TrustBridge is restarting it (attempt N of M)	A USB smart-card reader that Windows left failed (problem code 10), which Workstation 1.8.0 restarts by itself, up to three times.	Wait a few seconds.
The Tokens tab says A smart-card reader is plugged in, but Windows could not start it. Unplug it and plug it back in.	The restarts did not cure it, or the machine has Certificates:RestartFailedReaders off. The fleet row reads Reader failed, and the Dashboard counts it.	Unplug the reader and plug it back in, which also earns it a fresh set of restarts. A reader that keeps failing is the reader, its driver or its USB port.
An e-CNPJ is shown on the Tray App as not announced	The Server does not take Company certificates: it is older than 1.13.0.	Upgrade the Server.
The Tray App is not there after install	It starts at the next sign-in, or, after an upgrade, when the new service starts.	Sign out and in, open TrustBridge from the Start menu (Workstation 1.9.0 and later), or start Tray App\TrustBridge.TrayApp.exe.
The Tray App says Not connected	It could not open the service's pipe: the Workstation Service is stopped or restarting.	sc.exe query "TrustBridge Workstation Service"; the Application event log.
A policy change had no effect	The registry is read once, at start.	Restart-Service "TrustBridge Workstation Service".
A perfectly configured machine looks bare in the registry	A 32-bit PowerShell redirected to WOW6432Node.	Use a 64-bit PowerShell.
Every certificate on a machine is reported as ACTIVE, including sample ones	UseLacunaTestPki on, or a FakeTokens section in the settings file.	Remove both on any machine anybody signs from.

Why no Tray App could be asked

When a machine cannot put a PIN prompt in front of the holder, it says why. For a Signing Authorization it answers NO_TRAY (Workstation 1.9.0, recorded from Server 1.22.0); for a session-start PIN prompt it answers Undeliverable (Workstation 1.10.0, recorded from Server 1.23.0). The client is told only PIN_NOT_AVAILABLE. The operator reads the reason in two places:

• The machine's Events tab on the Workstations screen (Server 1.23.0), in words, with what to ask the holder and the code beneath.
• The Audit Log, as detail.reason on the signing.authorization-refused or pin.prompt-answered row, beside the Windows session at the console (consoleSessionId), the sessions a Tray App was attached in (traySessionIds) and the Tray's build (trayVersion). The Workstation id filter finds one machine's rows.

detail.reason	What the Events tab says	What to ask
TRAY_NOT_AT_CONSOLE	The holder was not at the console: on Remote Desktop, or another user had switched onto it.	Ask the holder to sign in at the machine itself, not over Remote Desktop.
NO_TRAY_RUNNING	No Tray App was running on the machine. A Tray that is still running but has dropped its connection to the service reads the same.	Ask the holder to open TrustBridge from the Start menu.
TRAY_CANNOT_SHOW_TRANSACTIONS	The Tray App running was too old to show what was being signed. (older than Workstation 1.6.0)	Ask the holder to close the Tray App and open TrustBridge again from the Start menu.
INSTALLING_RELEASE	A Workstation Release was being installed.	Ask the holder to try again in a few minutes.
TRAY_NOT_READING	The Tray App was running but not reading, so the prompt never reached it.	Ask the holder to close the Tray App and open TrustBridge again from the Start menu.
TRAY_DETACHED	The Tray App closed or crashed with the prompt on screen.	Ask the holder to open TrustBridge from the Start menu and try again.
SERVICE_STOPPING	The Workstation Service was stopping.	Ask the holder to try again in a few minutes.
NO_A1_PIN (a session-start prompt only)	No A1 PIN is set for the A1 Certificate on the machine.	Ask the holder to set an A1 PIN for the certificate in the Tray App on that machine.
No detail	No Tray App could show the prompt. The machine did not say why. for a Signing Authorization, or The prompt could not be shown on the machine, or its answer could not be used. for a session-start prompt	The machine runs a release before Workstation 1.9.0 (1.10.0 for a session-start prompt). Its Console Account cell, where it has one, says whether a Tray runs at the console.

A reason this Server does not know is shown as its code. The other Workstation Refusals read in words too: a prompt that timed out (Nobody answered the PIN prompt in time.: ask whether the screen was locked), a locked token (ask the holder to unlock it with its PUK), a PIN that did not match (ask the holder to check it before trying again). A decline, a Client Application that stopped waiting, and a call the holder authorized after its session had ended are marked as somebody's choice and are not counted against the machine.

Updating the fleet from the Server

Symptom	What it is	What to do
Upload refused: The package is not signed	A development build.	Upload the signed release package.
Upload refused: …signed by …, a certificate this Server's Publisher Pin does not list	Not a Lacuna release, or a package re-signed after it left Lacuna.	Upload the release package as Lacuna Software ships it.
Upload refused: The package's signature cannot be read	A copy damaged on its way.	Download the release again.
Upload refused: The package does not declare which protocol it speaks	A Workstation release before 1.3.0, or not a Workstation package.	Upload a current release.
Upload refused: The package speaks protocol N and this Server speaks M. Upgrade the Server first	The release is newer than the Server, for example Workstation 1.6.0 on a Server before 1.15.0.	Upgrade the Server, then upload.
Upload refused: …this Server accepts protocols N to M only	The release is too old for the Server: machines that installed it could not connect.	Upload a current release.
Upload refused: Workstation N is already stored	That version is already on the Server.	Nothing to do, or delete it first to replace it.
Upload refused: This Server cannot write its scratch directory	/tmp/trustbridge-releases is read-only or full.	The Server log names the directory and why. Mount a disk-backed volume over it: see the temporary directories.
On App Service, a large upload never finishes	The upload is one request, and the front end ends requests after about four minutes.	Upload over a faster link.
A release cannot be deleted	It is offered to machines, revoked ones included.	Withdraw from all on the Workstation Releases screen first.
A machine is left out of an offer	It is not Admitted, already runs that version or a newer one, has Updates disabled by policy, or Needs a manual update (Workstation 1.3.0 or older).	The reason is next to its name in the offer dialog. Update it by hand or by Group Policy.
A machine reports the update failed	msiexec failed or gave up: the detail panel shows its exit status and the end of its log. Exit 1618 (another install in progress) is retried by the machine fifteen minutes later.	Fix the cause on the machine, then offer the release again: a failed release is never retried on its own.
A machine reports the update refused	One of the machine's checks failed: hash, signature, timestamp, Publisher Pin, revocation, product or version.	The check is named on the row. A hash failure is usually a damaged download: offer it again.
Nothing moves after an offer	The machine waits up to ten minutes before downloading, then waits until no signature is in flight and no PIN prompt is open. Downloads over the Server's cap are told to come back later.	Wait. A machine that is offline picks the offer up at its next handshake.

Client application errors

Branch on error.code. The full vocabulary is on the REST API page.

Code	Usual cause	What to do
401 UNAUTHORIZED	Missing, mistyped, revoked or expired key, or a disabled application. All refused identically.	Check the key on the Client Applications screen.
401 SESSION_EXPIRED	The session idled out, was deactivated, was replaced by a newer one for the same CPF (and CNPJ), ran out of its Signature Allowance, or was vault-bound across a Server restart.	Create a new session. Nothing says which; that is deliberate.
400 INVALID_REQUEST on POST /v1/sessions naming cpf or cnpj	Check digits do not agree, or a repeated-digit value.	Fix the value at the source. Validate check digits in your form.
400 INVALID_REQUEST on POST /v1/sessions: pin is required., or details saying more than one certificate could serve it	No pin sent. Only an application with both Per-Transaction PIN and Sessions without a PIN on may leave it out, and even then only where exactly one certificate could serve the holder.	Send pin.
400 INVALID_REQUEST on a sign or a batch	No sessionId in the request. Or, from Server 1.15.0, a pin sent on a session whose transactionPin is not "client", or none on one whose transactionPin is.	Send the id POST /v1/sessions returned; send pin only where transactionPin is "client". Retrying unchanged fails identically.
403 HASH_SIGNING_NOT_GRANTED	The Client Application calls POST /v1/signatures/hashes without having been granted Hash Signing.	An Administrator turns on Hash Signing on the application's card, on the Client Applications screen.
404 CERT_NOT_FOUND	No certificate for the CPF (and CNPJ) is held anywhere: the token is not plugged in, the machine is not admitted or connected, or the CPF was never issued. For a session with a cnpj, also a machine before Workstation 1.5.0, which does not announce e-CNPJs.	The Certificate Registry and the fleet screen.
422 CERT_NOT_ACTIVE	Every certificate for the CPF (and CNPJ) is EXPIRED, REVOKED, UNTRUSTED or STALE. UNTRUSTED often means the deployment's anchors do not cover the issuer, or the Server's PKI licence was refused. For an application switched to REST PKI Core, also a certificate REST PKI Core's security context does not trust.	GET /v1/certificates/info for the verdict; the Certificate Registry for the issuer.
401 INVALID_PIN	Every machine holding a candidate certificate gave a PIN Proof and none checked against the PIN sent, and the PIN opened no Vault Certificate. Usually a wrong PIN, or a machine whose cached PIN is a different one.	Ask the holder. Five failures in fifteen minutes lock the CPF.
422 PIN_NOT_AVAILABLE	Nothing could be compared: the Tray prompt timed out, was declined, or nobody was signed in to answer it; an A1 Certificate with no A1 PIN set; a Vault Certificate could not be opened. Or details says too many recent proofs or passwords did not check, so the machine or the vault is not asked again until they age out of the window. On a signing call under a per-transaction session, details is declined, timed out, no Tray at the console, token locked, no A1 PIN at the workstation or too many calls waiting.	details says which. For a prompt, the holder must be at their machine with the Tray App running. A spent budget clears by itself. too many calls waiting: send one call at a time per holder.
422 WORKSTATION_OFFLINE	Every machine holding an active certificate for the CPF (and CNPJ) is offline, after the reconnect grace on a sign. A machine that has spent its failed-proof budget for this CPF counts as offline for session creation, and so, for a Client Application with Per-Transaction PIN on, does a machine on Workstation 1.5.0.	The fleet screen, and the Server log's Warning lines naming the machines passed over.
422 WORKSTATION_OFFLINE with details workstation removed	The session's machine, or the one a session being created chose, was removed by an Administrator. It will not come back under that session.	Create a new session once the holder's certificate is on an admitted machine again.
422 CERT_INCOMPLETE_IDENTITY	The certificate does not name its holder well enough to sign under them; details names the missing field. Only the Signer needs an e-mail address: an application switched to REST PKI Core signs without one.	If it is the e-mail address, send email when creating the session. Any other field is the certificate's own: sign with another certificate.
422 SIGN_TIMEOUT	The signature did not finish within Signing:RequestBudget (60 s). A slow machine or a slow Signer.	The Signing Operations screen shows the stage reached.
422 SIGNER_REJECTED	Lacuna Signer was reached and refused the request: usually the document itself, occasionally something else the request named. details carries its account. Retrying unchanged reproduces it.	Read details, then fix the document or the request.
422 UNSUPPORTED_DOCUMENT	Not a PDF. For an application switched to REST PKI Core, also a PDF REST PKI Core cannot sign: corrupted or password-protected, or one already signed, under a subscription whose PDF marking policy is Always.	Send a PDF it can sign.
502 SIGNER_ERROR	Signer could not be asked: unreachable, rate-limiting, or answering a fault of its own. Nothing was signed, so the same document may be sent again once it is back. A Signer that turns down this Server's own credential arrives here too. For an application switched to REST PKI Core, REST PKI Core unreachable, failing, timing out or out of its subscription's quota.	Signer's availability, Signer:BaseAddress and Signer:ApiKey; or REST PKI Core's, and RestPkiCore:Endpoint.
409 DOCUMENT_NOT_READY that never clears	The signature is still in flight, or a run was stranded by a restart and Signer still holds the document open.	The Signing Operations screen; RUN_STRANDED.
429 SERVER_BUSY during ordinary use	Throttle:ConcurrencyLimit set too low for the deployment, not a client problem.	Raise it. Under a genuine spike, retry with backoff and jitter.
429 TOO_MANY_PIN_ATTEMPTS	The per-CPF lockout, whichever cnpj was sent.	Wait for the window (15 min) to pass. Retrying makes it worse.
404 ENDPOINT_NOT_FOUND	A route without the /v1 prefix.	Fix the URL.
413 DOCUMENT_TOO_LARGE	Over Signing:MaxDocumentBytes (10 MB by default).	Smaller document, or raise the cap knowing what it costs.
500 INTERNAL_ERROR on a sign, with could not be opened by the reader this platform signs with in the Server log	A Vault Certificate imported before the legacy-shape check existed, shrouded under pkcs5PBES2.	Re-export with openssl pkcs12 -export -legacy and import again. That needs the original file.
500 INTERNAL_ERROR on every sign of an application switched to REST PKI Core	A key REST PKI Core refuses, a key without the Worker role, a security context it does not have, or no RestPkiCore section any more. Nothing was signed.	The Error line in the Server log names which.

Signing outcomes on the Signing Operations screen

A Failed operation carries a failure code and the stage it reached: the client's 202 may have been answered long before. RUN_STRANDED means the Server was restarted under the run and a sweep ended it. A run that failed after the document reached Signer leaves a document open there, which the fetch reports as 409 until Signer's own retention or the tidy-up ends it as 422.

Since Server 1.23.0 the screen says each failure in words, with what to ask the holder, and whether the holder's token signed. A PIN_NOT_AVAILABLE names what the Workstation answered: no PIN cached (ask the holder to enter it at the Tray App), a PIN the token rejected, a locked token (its PUK), or a Signing Authorization the machine no longer held. Failed (24h) groups the day's failures by those causes. A run pending longer than a live run can last is tinted and says what it is waiting on. A signing call the machine refused is not here at all; it is in the machine's Events tab.

A document signed with REST PKI Core records its own stages, rest-pki-core-prepare and rest-pki-core-complete. On that path a document gets its id only once REST PKI Core has completed it, so a failure before then is a refusal rather than a 202. A refusal after the holder's key signed promises nothing either way: the Signature Allowance charge is spent, and REST PKI Core may still hold a signed document no id names, so sending the document again signs it again. Where that may be so, as for a completion left unanswered or a stranded run whose completion had begun, an Error line in the Server log says it.

An operation whose Ran on reads removed workstation and a short id ran on a machine an Administrator has since removed; the admin.workstation-removed row in the Audit Log names it.

Getting help

Send Lacuna Software support the X-Correlation-Id of the failing request, the Server version shown in the admin console's navigation drawer, the workstation package version from the fleet screen, and the relevant Server log lines. For a workstation problem, add the machine's Workstation Report from its detail panel on the fleet screen, where it has one, the codes its Events tab shows beneath each refusal, and the Application event log entries from source TrustBridge Workstation Service. Never send a PIN, an API key, the Key Ring Protector or the licence.