Quick answer
Alfresco search is eventually consistent: Solr trackers poll the repository and index changes after they commit, so documents appear in search only once tracking catches up. When documents never appear, the cause is one of five things — index lag, stalled tracking, failed transactions, failed content transforms, or stale permissions — in roughly that order of likelihood. The diagnostics and fixes for each are below, with the exact console URLs.
01 — What You’re Seeing
The document is in the repository. Search says it isn’t.
Confirm you’re on the right page before you touch anything.
One or more of these signatures, on Alfresco Content Services 7.x with Search Services (Solr):
- A document uploaded minutes or hours ago is not in search results, but opens fine by direct link or folder browse.
- Search finds a document by name but not by its contents — full-text queries miss what metadata queries hit.
- An admin finds the document; a regular user doesn’t, with no recent permission change anyone will admit to.
- The Admin Console’s Search Service page shows approximate transactions remaining climbing instead of trending to zero.
solr.logshows tracker exceptions — connection refused, 401/403 from the repository’s/api/solrendpoints, or transform errors.
None of this means the index is corrupt, and a full rebuild — the reflex fix, and on a large repository a day-long one — is almost never the first move. Work the causes in order instead. (The full set of what Reveille checks on this platform is in the Reveille for Hyland Alfresco technical overview.)
02 — Causes, Ranked by Likelihood
Five causes account for nearly every case
Confirm before you fix — each cause has a cheap, specific test.
This is the same failure shape we documented on Documentum when search stops returning documents: the repository and its index are separate systems, and the pipeline between them fails silently. On Alfresco that pipeline is the Solr trackers.
| # | Cause | How to confirm | Fix, in short |
|---|---|---|---|
| 1 | Index lag — trackers healthy but behind the repository | Admin Console → Search Service: transactions remaining is falling. action=SUMMARY timestamps are recent. | Let it drain; fix the bottleneck (Solr heap, CPU, disk I/O) if lag recurs daily. |
| 2 | Tracking stalled — repository ↔ Solr communication broken | Lag only grows. solr.log shows connection refused or 401/403 — typically a secure-comms mismatch (shared secret or mTLS keystores), often after an upgrade. | Restore comms on both sides; tracking resumes where it left off. |
| 3 | Failed transactions — specific changes errored during indexing | action=REPORT index error count > 0; the EXCEPTIONMESSAGE query below returns nodes. | Resolve the root error, then schedule reindexing with action=FIX. |
| 4 | Transform failures — metadata indexed, content not | Name search hits, full-text misses. transformationStatus:transform_failed or no_transform queries return nodes. | Restore the Transform Service; reindex the affected transactions. |
| 5 | Stale permissions — ACL changes not yet indexed | Admin finds it, the user doesn’t; recent permission or group change on the path. | Let ACL tracking catch up; action=FIX also reconciles ACL change sets. |
A sixth, honorable mention: nothing is broken and the expectation is wrong. Search Services is eventually consistent by design — a document committed one second ago is supposed to be invisible for a few more. If your lag is seconds and your users expect zero, that’s an architecture conversation (transactional metadata queries exist for exactly this), not an incident. Community threads on Solr indexing lag are full of healthy systems being restarted into actual problems.
03 — The Fixes
Work them in repair order
Every URL below runs against the Solr host (default port 8983). Lock these endpoints down — if they’re open to you, they’re open.
1. Measure the lag before touching anything
Admin Console → Search Service shows approximate transactions remaining. From the Solr host, the core summary gives tracker state and timestamps:
Falling lag: stop here, let it drain. Growing lag with no tracker errors: Solr is resource-starved — heap, CPU, or disk I/O. Growing lag with tracker errors in solr.log: cause 2.
2. Restore tracking if it has stalled
401/403 on the repository’s /api/solr endpoints means the secure channel between repository and Solr is misconfigured — a shared-secret mismatch or expired mTLS keystores, and an upgrade on one side but not the other is the classic trigger. Align the configuration on both sides and restart Solr; the trackers resume from their last recorded transaction. Nothing is lost while tracking is down — it queues.
3. Find and reindex failed transactions
Check the index error count and find the failed nodes with the exception query:
Fix the underlying error first — FIX reschedules indexing; it does not repair the condition that failed it. Then run FIX as a dry run, review what it reports, and apply:
FIX compares the database against the index and schedules missing, duplicate, or extra transactions and ACL change sets for reindexing on the normal tracking cycle. maxScheduledTransactions defaults to 500, so bound the time range on a large repository and run it in passes; a successful call returns "status": "scheduled". (Zia Consulting’s guide to the Solr FIX action covers the parameters in depth.)
4. Catch the content that never got indexed
If names hit and contents miss, the text transform failed and Solr holds metadata-only entries. Two queries find them, faceted by MIME type so you can see what class of file is failing:
A Transform Service outage during a bulk load is the usual story — everything uploaded in that window is findable by name and invisible by content, and nothing alerts, because the uploads all succeeded. Restore transforms, then reindex the affected window with FIX. Oversized, encrypted, and corrupt files will never transform; a small persistent count here is normal.
5. Rebuild only when the index itself is the casualty
Full reindex — wipe the index directory and let trackers rebuild from transaction zero — is for genuine corruption or failed migrations, not for lag. On a large repository it runs for many hours to days, during which search degrades for everyone. If you must: schedule it, size Solr’s heap and disk for the rebuild, and verify the lag query returns numFound: 0 at the end.
04 — How to Stop It Recurring
The failure is silent by design. The watch can’t be.
Every cause above shares one trait: nothing tells you.
The repository stays up the whole time. Uploads succeed. Platform checks stay green. The only signals — tracker lag, index error counts, transform status — live on Solr admin endpoints that no infrastructure monitor reads and no one opens until users complain. Platform SLA is not workflow SLA, and “documents are findable” is a workflow SLA. The durable fix is to put the index pipeline itself under continuous watch: lag trending, not just measured once; the error count checked every few minutes; a real search executed end-to-end as a user would run it.
Reveille for Hyland Alfresco
Reveille ships with over 35 pre-configured Alfresco-specific tests and over 45 Alfresco dashboard metrics for Alfresco 7 and above — including Check Alfresco Search System Health, Alfresco Search Core Health, Alfresco Search Thread Health and Metrics, Alfresco Search Server Connectivity, and a synthetic web-client pass that logs in, searches, retrieves a document, and logs out. Every failure chain on this page trips one of those tests before a user files the ticket. See the Reveille Enterprise platform →
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.
Take it with you
Running Alfresco in production?
The complete map of what Reveille tests and measures on Alfresco — the technical overview as a PDF. Enter your email and it opens.
The overview is also published ungated on this site. The PDF is the same document.
Quick answers
