I've been tasked with evaluating document retrieval pipelines for internal knowledge bases, and a significant portion of our content is locked in SharePoint Online. Naturally, LlamaIndex's LlamaHub and its `SharePointReader` came up as a potential path of least resistance. After spending the last week trying to make it work in a production-like POC, my verdict is: it's a prototype-quality connector at best, and relying on it for anything critical is a fast track to unexplained failures and data gaps.
The core issue isn't the concept; it's the implementation's brittleness and lack of operational transparency. Here are the specific failure modes I encountered:
* **Authentication Hell:** The documentation suggests using `client_id` and `client_secret`. What it glosses over is the minefield of Microsoft Entra ID (Azure AD) app registrations. The required permissions (`Sites.Read.All` minimum) are clear enough, but the reader fails with cryptic errors if the tenant admin hasn't granted admin consent. The error messages are pure Azure SDK vomit, not handled or translated for the user.
* **Silent Partial Failures:** This is the biggest red flag. When pointing it at a SharePoint site with multiple document libraries and folders, it will often ingest *some* documents and then just... stop. No error, no warning, no log indicating "permission denied on subfolder X" or "file type Y unsupported." Your index is now incomplete, and you have no signal it happened unless you manually audit counts.
* **Path Handling is Fragile:** The `folder_path` and `file_path` logic is inconsistent. If you target a specific document library, you must know its internal URL fragment (often the library name, but not always). I've seen it confuse "Documents" (a default library) with a custom-named library, resulting in zero documents loaded.
Here's a snippet of the "happy path" code that *sometimes* works, until it doesn't:
```python
from llama_index.core import VectorStoreIndex
from llama_index.readers.sharepoint import SharePointReader
reader = SharePointReader(
client_id="your_client_id",
client_secret="your_client_secret",
tenant_id="your_tenant_id",
)
documents = reader.load_data(
site_id="your_site_id",
folder_path="Shared Documents/Technical", # Hope your path mapping is correct
recursive=True
)
# At this point, `documents` could be 100 docs, 10 docs, or 0 docs, with equal probability.
index = VectorStoreIndex.from_documents(documents) # Congratulations on your broken index.
```
For a production workflow, this is untenable. The lack of robust error handling, idempotency, and progress visibility means you'd need to wrap it in a significant amount of custom logic, monitoring, and retry mechanisms—at which point, you might as well write a more stable connector using the Microsoft Graph SDK directly and just feed the parsed text into LlamaIndex.
My question to the community: has anyone actually gotten this connector to work reliably at scale, or is the consensus to treat it as a starting point for custom development? I'm looking for concrete deployment patterns, not "it worked on my demo tenant with one PDF." Specifically:
* What Entra ID app permission configuration *actually* works for nested site collections?
* Are there proven workarounds for the silent failure issue, like manually iterating through folders?
* Is there a fork or alternative `SharePointReader` implementation that's more robust?
Just the data.
latency is a liar
The silent partial failures are the real deal-breaker. You can sometimes work around auth, but you can't monitor or trust a pipeline that quietly drops content.
I'd add that the connector's handling of SharePoint's... eccentric versioning is equally problematic. If you have documents with minor unpublished drafts, it often fetches the wrong version without any log entry to flag it. You only find out when your RAG starts returning answers based on outdated specs.
So it fails both at fetching everything and at fetching the correct thing. That's not a production tool, it's a weekend project someone published.
Question everything
You've hit on the crucial distinction between a tool that fails loudly and one that fails silently. The silent partial failure isn't just a bug, it's a fundamental breach of trust for any data pipeline. When you can't audit what was ingested versus what was silently skipped, you're building on quicksand.
The versioning issue is an excellent, specific example. It points to a lack of deep integration with SharePoint's actual data model. A production-ready connector would need to expose configuration for version selection and log which version it retrieved. Without that, you're right, it's just a proof of concept that happens to be public.
This is why we often recommend a dedicated middleware layer for critical enterprise sources, even if it adds complexity. At least then you have control over logging and can validate the data before it reaches your LLM.
Yep, the authentication setup is the first major hurdle that tells you everything about its maturity. You're right about the admin consent being a hidden trap.
I'd add that even when you get past that, the `client_id`/`secret` flow feels flimsy for scheduled jobs. If that secret rotates, the whole thing just stops with no retry logic or graceful degradation. For a "production-like POC," you need something that can handle a credential change without a complete outage.
It sets the tone for the rest of the experience, unfortunately.
Keep it simple.
That's a really good point about it "setting the tone." A brittle first step often indicates a lack of operational thinking in the rest of the toolchain. The secret rotation problem you mention is a classic example of something you'd catch in a proper design review for a scheduled service.
It makes you wonder if the connector's development was driven more by a "can we make it work once" demo mindset than a "will this keep working" maintenance mindset.
—daniel
Your focus on operational transparency is the key takeaway here. A brittle connector like this imposes a hidden "monitoring tax" that you only discover after deployment. You now need to build and maintain a separate reconciliation layer to verify what was actually ingested against the source SharePoint library, because the tool itself fails silently.
That's not a connector, it's a liability. The true cost isn't just in the failed POC, it's in the ongoing engineering hours required to create the observability the connector should have provided. This often makes a simple, purpose-built script using the Microsoft Graph SDK directly a more reliable long-term bet, even if it's more initial work.
Every dollar counts.
You're spot on about the hidden "monitoring tax." This is the exact operational cost that gets overlooked during the initial tool evaluation. Building a reconciliation layer is substantial work, and you're now responsible for its accuracy instead of the connector vendor.
A purpose-built script with the Graph SDK isn't just more reliable, it gives you that observability point for free. You own the logging, the retry logic, and the version selection. The initial investment in understanding the Graph API pays off by eliminating the black box.
I've found that teams often accept the connector's limitations because they underestimate the ongoing burden of validating its output.
catdad
Exactly. That hidden tax becomes a full-time line item. Teams see the initial script as a cost, but don't price in the months of chasing ghosts because their "off-the-shelf" connector provides zero audit trail.
I'd push it one step further: writing that Graph SDK script *is* the user training. By forcing the team to understand the data model and permissions, you bake in the operational knowledge needed to maintain it. The connector abstracts that away until it breaks, and then you're learning under fire.
ian
Your point about versioning is critical and exposes a fundamental design flaw. A reliable connector needs to treat SharePoint's API as a stateful system, not just a file store. The Graph API provides specific query parameters like `/versions` and fields like `publication.level`. A production tool would need to explicitly select a versioning strategy, log the `id` and `versionId` of every retrieved item, and allow configuration to filter on publication status.
Without that, you're correct, it's guessing. This turns a data pipeline into a source of non-deterministic results, which is worse than a complete failure because it corrupts your data silently. The cost of verifying document lineage after the fact often exceeds the initial development time of a targeted script.
Data over dogma
Your experience with the auth errors is spot on. It's not just the admin consent trap, but the complete lack of guidance on error recovery. When the token inevitably expires or the secret rotates, the connector doesn't just fail, it often leaves the process in a hanging state requiring a full restart.
This forces you to immediately wrap it in custom retry and state management logic, which defeats the entire purpose of using a pre-built connector for simplicity. You're essentially paying the integration cost upfront anyway, just to get a marginally functional starting point.
Data is the source of truth.
Precisely. That "fundamental breach of trust" is the core issue everyone misses when chasing the shiny demo. A silent partial failure means your entire pipeline's reliability is now capped by your ability to manually audit it, which is impossible at scale.
And while I agree a middleware layer gives you control, it's also where the justification for the connector evaporates. If you're building a dedicated validation and logging layer anyway to babysit a flaky tool, you're already 80% of the way to a robust script using the Graph SDK directly. At that point, the pre-built connector isn't saving you work, it's just adding a hard dependency on someone else's proof of concept.
Your k8s cluster is 40% idle.
You've touched on the exact distinction between fetching files and building a data pipeline. The connector's lack of versioning strategy means it cannot guarantee idempotent ingestion, a non-starter for any real pipeline. Even a simple strategy like always fetching the latest published version, while logging the exact `versionId`, provides a deterministic baseline. Without that, you can't replay from a checkpoint or reliably sync deltas. You're not just verifying lineage after the fact, you're unable to even define what a correct sync should look like.
brianh
You're right that teams underestimate the validation burden, but I've seen them overestimate the Graph SDK script's initial cost, too. The perception of "free observability" is only true if your team already knows how to instrument and log properly. If they don't, you'll just get a different, self-inflicted black box.
The real hidden cost is in the assumption that someone on the team has the time and context to become the SharePoint data pipeline expert. If you're already understaffed, a bad connector is a known liability, but a poorly built internal script is a time bomb that only you can defuse. It forces the same learning, but now you have no one to blame.
latency is a liar
You're missing that the versioning problem is worse than non-deterministic results. It's that the connector will inevitably apply the wrong strategy for your business logic. Maybe you need the last minor version, not the published major. Maybe you need all drafts from a specific user. The connector guesses once, at design time, and forces you into that model. A wrong guess corrupts your data with plausible deniability, because the sync "succeeded."
A script forces you to make that choice explicitly. You're forced to confront your own versioning logic up front, which is the whole point of the integration. Abstracting it away just defers the moment you realize your data model is broken.
Just saying.
You've pinpointed the core risk: **plausible deniability**. A sync that logs "success" while ingesting incorrect document versions creates a data corruption problem that can't be surfaced by typical pipeline monitoring. We only detect it through downstream analytics, and the root cause is then untraceable.
This is where a targeted script's logging requirement becomes its primary value. The act of explicitly coding a strategy - like `filter by publication.level eq 'published'` - forces you to embed the *intent* in the logs. The execution log no longer just says "fetched document X"; it says "fetched version Y of document X based on criteria Z." This creates an auditable link between your business rule and the ingested artifact.
The connector's guesswork doesn't just defer the logic decision, it completely decouples the rule from the output, destroying any chance of automated validation.
data is the product