Quick answer
Most Hyland OnBase trouble lands in one of five buckets: slow clients (usually database blocking or an Application Server under strain), Workflow items that stop moving (a timer that did not execute, or work that cannot complete), batches stuck in a queue (Disk Group or lock problems), integrations that stop answering (sessions, credentials, endpoints), and logins that fail (directory, identity provider, or user configuration). Each one has a first check that rules in or out the common cause in minutes. They are below, in order.
OnBase rarely fails loudly. The servers stay up, the services say Running, and the platform dashboards stay green while invoices stop moving, batches sit in Awaiting Commit, and the help desk fills with “OnBase is slow.” This page is the triage order for those calls: the symptom, the first thing to check, and the fix.
Two of these buckets have their own full write-ups — Workflow timers not firing and Unity Client troubleshooting. (The full catalog of OnBase health checks and tests is published here, ungated.)
01 — The Symptoms
What is wrong with OnBase? Five symptoms and the first check for each
Match the call you just took, then jump to the fix.
| # | What users report | Most likely cause | First check |
|---|---|---|---|
| 1 | “OnBase is slow” — retrievals lag, searches time out, Unity Client says the Application Server is not responding | Database blocking or deadlocks; Application Server worker recycling or out of memory; a heavy import, OCR, or indexing job running at the same time | SQL blocking on the OnBase database at the time of the complaint |
| 2 | Workflow items stop advancing; escalations and overnight transitions never happen | The scheduling service is not executing timers on the assigned server, or timer work is blocked by locks or a failing external action | Evidence that one specific timer ran after its scheduled time |
| 3 | Scanned or imported documents never show up; batches sit in Awaiting Commit, Awaiting Index, or Incomplete | Disk Group full, offline, or locked; stale batch or process locks; a stopped import or scanning service; a watched folder with bad permissions | Disk Group status and the lock list in the Configuration module |
| 4 | The ERP, CRM, or RPA integration stops syncing; API calls time out or return authentication errors | Expired or changed service-account credentials; Application Server session exhaustion; a renamed endpoint or certificate; a Unity API or REST dependency not updated after an upgrade | The integration’s own log for the first failed call and its error text |
| 5 | Users cannot log in; permission errors; a group’s rights do not apply | Directory or identity provider not answering; locked or expired account; wrong user group or security keyword configuration; client pointed at an Application Server that is down | Can one known-good user log in from one known-good machine? |
The first check in every row is a differential, not a fix. It separates “the platform is unhealthy” from “one thing in the platform is stuck,” which is the whole game in OnBase triage. A full-estate slowdown with no database blocking points at the Application Server; blocking with a healthy Application Server points at whatever was holding the lock. One user who cannot log in while another can is configuration; nobody logging in is the identity provider or the server.
02 — The Fixes
How do you fix each OnBase problem? The repair sequence
In order within each symptom. Restarting the Application Server before reading the evidence loses the evidence.
-
Slowness: look at the database before the servers
On the OnBase SQL Server, check for blocking and deadlocks at the time of the complaint (sp_who2 or the blocked-process report, and the deadlock graph in the SQL error log). A long-running report query, a DIP import, or an unindexed keyword search holding a lock explains most “everyone is slow” calls. If the database is clean, go to the Application Server: check the IIS worker process for recycles and memory pressure in the Windows event log, and review the Application Server diagnostics for request queues and timeouts. Then ask what else was running — OCR, full-text indexing, a COLD process, a Document Retention run — and move it off the business window.
-
Workflow: verify execution, then the service, then the work
Pick one timer that should have fired and find its output in the Workflow log. If it did not run, confirm the scheduling service (the Unity Scheduler, or the legacy Workflow Timer Service in older configurations) is running on the server the timer is assigned to, and that timers were not left on a deprecated binding by an upgrade. If the timer ran but items did not move, the work could not complete: check for held document, batch, and process locks, for database deadlocks at run time, and for the external script, notification, or integration the timer calls. The full sequence is in OnBase Workflow timers not firing.
-
Capture: free the Disk Group, clear the lock, restart the owner of the next step
In the Configuration module, confirm the Disk Group the batch writes to is online, has free volumes, and is not locked. Release stale batch and process locks left by crashed client sessions. Then restart the service that owns the stuck step — the scanning workstation’s Unity Client, the Document Import Processor, or the COLD process — and confirm the batch advances. For watched-folder imports, test that the service account can read and delete in the folder; a permissions change on a file share silently stops every import that uses it.
-
Integrations: read the first failed call, not the hundredth
The integration’s own log tells you which of three things broke. An authentication error after a password rotation or certificate renewal is credentials: update the service account in the integration and in OnBase. A timeout with a healthy Application Server is usually session exhaustion: check active sessions and the API session licenses in use, and make sure the integration disconnects sessions instead of leaking them. A hard failure after an upgrade is a dependency: the Unity API client, REST endpoint version, or DLL the integration was built against. Re-run one call by hand from the integration server to confirm the fix before letting the queue drain.
-
Logins: narrow to one user, one machine, one server
If nobody can log in, the directory service, Hyland IdP, or the Application Server is down; check the identity provider first, then whether the Application Server can reach the database. If one user cannot, check the account (locked, expired password, disabled in AD or in OnBase), then the user’s group membership and the group’s privileges and security keywords. If one machine cannot, the client is pointed at the wrong Application Server URL or a certificate it does not trust. Fix the one thing that differs.
03 — Prevention
How do you stop troubleshooting OnBase from the help desk queue?
Every symptom above was visible before the first ticket. Just not to the tools that were watching.
Each of the five failures has the same shape: the infrastructure monitor says healthy, because the server is healthy, while the thing the business depends on — a retrieval under two seconds, a batch that commits, a timer that fires, a login that succeeds — has already stopped. Platform SLA is not workflow SLA. The durable fix is to check those outcomes continuously, as a user would, and alert on the first miss. Reveille for Hyland OnBase ships over 80 pre-configured OnBase tests that cover exactly these chains: Check OnBase Web Client Login, Search, Retrieve, and Logout and OnBase Unity Client Login and Retrieve for symptom 1 and 5; Workflow Timer Errors and Workflow Timer Never Ran for symptom 2; Check Disk Groups, Uncommitted Batches, Disk Group Locks, Process Locks, and Batch Locks for symptom 3; OnBase REST API Obtain Access Token, Upload Document, and Retrieve Document for symptom 4; and OnBase Database Deadlocks/sec under all of them.
Reveille for Hyland OnBase
Agentless observability for OnBase — over 80 pre-configured tests and over 85 dashboard metrics, including the synthetic login, retrieve, batch, lock, and timer checks named above. The full catalog is linked above, ungated.
Supporting client estates as an MSP, SI, or ISV? That’s what Reveille SENTRY is built for — multi-tenant observability for the estates you manage.
Frequently asked questions
